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GENERAL INTRODUCTION 


The Advance DOS Programmer’s Reference Manual is a technical reference 
manual for system programmers. | , 


Chapter 1 gives a description and examples of all Advance DOS system calls and 
interrupts. Chapter 2, Advance DOS 2.11 Device Drivers’ contains information on 
how to install your own device drivers on Advance DOS and gives an example of 
a device driver program. Chapters 3, 4 and 5 contain technical information about 
Advance DOS, including Advance DOS disk allocation (Chapter 3), Advance 
DOS control blocks and work areas (Chapter 4), and EXE file structure and 
loading (Chapter 5). Appendix A covers the ANSI Escape Sequences. Appendix 
B gives a sample run illustrating the use of EDLIN, MASM, LINK, EXE2BIN and 


DEBUG. 
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| CHAPTER 1 
SYSTEMS CALLS 


1.1 INTRODUCTION 

Advance DOS provides two types of system calls: interrupts and function requests. 
This chapter describes the environments from which these routines can be 
called, how to call them, and the processing performed by each. 


The system calls mean you don’t have to invent your own ways to perform these 
primitive functions, and make it easier to write machine-independent programs. 


1.2.1 Calling From Macro Assembler 

The system calls can be invoked from Macro Assembler simply by moving any 
required data into registers and issuing an interrupt. Some of the calls destroy 
registers, so you may have to save registers before using a system call. The 
system calls can be used in macros and procedures to make your programs more 
readable; this technique is used to show examples of the calls. 


1.2.2 Calling From A High-Level Language 
The system calls can be invoked from any high-level language whose modules 
can be linked with assembly-language modules. 
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1.2.3 Returning Control To Advance DOS 
Control can be retumed to Advance DOS in any of four ways: 


1. Call Function Request 4CH 


MOV AH,4CH 
INT 21H 


This is the preferred method. 


2. Call Interrupt 20H: 
INT 20H 


3. Jump to location 0 (the beginning of the Program Segment Prefix): 
JMP 0 


Location 0 of the Program Segment Prefix contains an INT 20H 
instruction, so this technique is simply one step removed from the 
first. 


4. Call Function Request OOH: 


MOV AH,00H 
INT 21H 


This causes a jump to location 0, so itis simply one step removed 
from technique 2, or two steps removed from technique 1. 


1.2.4 Console And Printer Input/Output Calls 
The console and printer system calls let you read from and write to the console 
device and print on the printer without using any machine-specific codes. You 
can still take advantage of specific capabilities (display attributes such as 
positioning the cursor or erasing the screen printer attributes such as double- 
Strike or underine, etc.) by using constants for these codes and reassembling 
once with the correct constant values for the attributes. 


- ———e + oo ame + So ae eee ee - +o . we ae «ep cewerems <+- mer « — 


1.2.5 Disk I/O System Calls 

Many of the system calls that perform disk input and output require placing values 
into or reading values from two system control blocks: the File Control Block 
(FCB) and directory entry. 
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"3.3. Fit CONTROL BLOCK (FCB) 
_ The Program Segment Prefix includes room for two FCBs at offsets 5CH ang 


6Cit. The system call descriptions refer to unopened and opened FCBs. An 
unopened FCB is one that contains only a drive specifier and filename, which can 
contain all fields filled by the Open File system call (Function OFH). Table 1.1 


describes the fields of the FCB. 
Table 1.1 Fields of File Control Block (FCB) 


Name Pers Hex acs Decimal thax Fc(8 A ee Fring 
Drive number 1 OOH 0 Q9o-Ro, -- ‘ +i St per 
Filename g 01-08H 1-8 31 ~ 08 |88-$F "87-99 
Extension 3 o9-08H ~=—ssoag-t «9, - BB JQ -2™ 

Current block 2 OCH,ODH 12.13 SC >. & D 13 -97 

Record size 2 OEH,OFH 14,15 JE - &F ™$- gl 

File size 4 10-13H = 16-19 YO - 93 ‘qa .gf 

Date of last write 9 14H,15H 292;  Ya~ G&S 34 -5¢ . 
Time of last write 2 16H,17H 22.20 ob B+ a) -A6 

Reserved 8 18-1FH = -24-31 GA HF 4k- AL 

Current record 1 20H 32 A P = rs 4}- A+ 

Relative record 4 a1-24H 8©=—a3-ae Ath - Ay AQ- At . 


1.3.1 Fields Of The FCB 
Drive Number (offset OOH): Specifies the disk drive; 1 means drive A: and 2 


means drive B:. If the FCB is to be used to create or open a file, this field can be set 
to 0 to specify the default drive; the Open File system call Function (OFH) sets the 
field to the number of the default drive. 


Filename (offset 01H): Eight characters, left-aligned and padded (if necessary) 
with blanks. If you specify a reserved device name (such as LPT1), do not put a 


colon at the end. 
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—— 


Extension (offset O9H): Three characters, left-aligned and padded (if necessary) 
with blanks. This field can be all blanks (no extension). 


Current Block (offset OCH): Points to the block (group of 128 records) that 
contains the current record. This field and the Current Record field (offset 20H) 
_ make up the record pointer. | This fi eld i is set to 0 by the Open Fi Fi le system call. 


-—s = 
= 


‘Record oe detent OEH): The size of a logical record, in bytes. Set to 128 ~ the 
Open File system call. If the record size is not 128 bytes, you must set this field 


after opening the file. 


File Size (offset 10H): The size of the file, in bytes. The first word of this 4-byte 
field is the low-order part of the size. 


Date of Last Write (offset 14H): The date the file was created or last updated. The 
year, month, and day are mapped into two bytes as follows: 

Offset TSA, 

IYIYI YT YT Y TY, yIM| 

ike 98 


Offset 14H — 
IM|M|M|{D|D|D|D]D] 
54 O 


Time of Last Write (offset 16H): The time the file was created or last updated. The 
hour, minutes, and seconds are mapped into two bytes as follows: 


Offset 17H 
[H| H] H]H] H [M [M|M| 
15 Vt 1G 


Offset 16H 
jn [n|s|s[s/s{s| 
54 0 


Reserved (offset 18H): These fields are reserved for use by Advance DOS. 


Current Record (offset 20H): Points to one of the 128 records in the current block. 
This field and the Current Block field (offset OCH) make up the record pointer. 
This field is not initialized by the Open File system call. You must set it before 


doing a sequential read or write to the file. 
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Relative Record (offset 27H): Points to the currently selected record, counting 
from the beginning of the file (startng with 0). This field is not initialized by the 
Open File system call. You must set it before doing a random read or write to the 
file. If the record size is less than 64 bytes, both words of this field are used; if the 


recordsize is 64 bytes or more, only the first three bytes are used. 


NOTE 


If you use the FCB at offset 5CH of the Program 
Segment Prefix, the last byte of the Relative 
Record field is the first byte of the unformatted 
parameter area that starts at offset 80H. This is 
the default Disk Transfer Address. 


1.3.2 Extended FCB 


The Extended File Control Block is used to create or search directory entries of 
files with special attributes. It adds the following 7-byte prefix to the FCB: 


Size Offset Ye 
Name (bytes) (Decimal) tla 
Flag byte (255, or FFH) 1 or a 2s 4 
Reserved § -6 wb- 3AH 
Attributed bute: 1 = 42H 


02H = Hidden file 
04H = System file 


1.3.3 Directory Entry 


ER 
,e> 4% 


4 


A directory contains one entry for each file on the disk. Each entry is 32 bytes: 


Table 1.2 describes the fields of an entry. 


ee ae - 
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Table 1.2 Fields of Directory Entry 


size Offset 
Name (bytes) Hex Decimal 
Filename 8 00-07H 0-7 
Extension 3 ' 08-0AH 8-10 
Attributes 1 OBH 11 
Reserved 10 OC-15H 12-21 
Time of last write 2 16H,17H 22,23 
Date of last read 2 18H,19H 24,25 
Reserved 2 1AH,1BH 26,27 
File size 4 1C-1FH 28-31 


1.3.4 Fields Of The FCB 
Filename (offset OOH): Eight characters, left-aligned and padded (if necessary) 
with blanks. Advance DOS uses the first byte of this field for two special codes: 


OOH (0) End of allocated directory 
E5H (229) Free directory entry 


Extension (offset O8H): Three characters, left-aligned and padded (if necessary) 
with blanks. This field can be all blanks (no extension). 


Attributes (offset OBH): Attributes of the file: 


Value 
Hex Binary Dec Meaning 


O1H 0000 0001 1 #£zRead-only 

O2H 0000 0010 2 » Hidden 

04H 0000 0100 4 + System 

O7H 0000 0111 7 Changeable with CHGMOD 
O8H 0000 1000 8 _ Volume-ID 


OAH 0001 0000 10 : Directory 
16H 0001 0110 22 Hard attributes for FINDENTRY 


20H 0020 0000 32 Archive 


Reserved (offset OCH): Reserved for Advance DOS 


Time of Last Write (offset 16H): The time the file was created or last updated. The 
hour, minutes, and seconds are mapped into two bytes as follows: 


Offset 17H 
IH |[H|H|HIH{M [mM (M| 
15 +t 10 


ee eee 
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Offset 16H 
MMMSSSSS5 

54 0 


Date of Last Write (offset 18H): The date the file was created or last updated. The 
year, month, and day are mapped into two bytes as follows: 


Offset 19H | 
IyYiytylyly ly ly [MI 
+o 98 


Offset 18H. 
|MIM|M|D|D|D |D |D| 
5 4 ) 


File Size (offset 1CH): The size of the file, in bytes. The first word of this 4-byte 


. field is the low-order part of the size. 


1.4 SYSTEM CALL DESCRIPTIONS 


Many system calls require that parameters be loaded into one or more registers 
before the call is issued; most calls return information in the registers (usually a 


code that describes the success or failure of the operation). The description of 
system calls OOH-2EH includes the following: 


A drawing of the 8086 registers that show their contents before 
and after the system call. 


A more complete description of the register contents required 
before the system call. 


A description of the processing performed. 


‘A more complete description of the register contents after the 
_ system call. | 


An example of its use. 


The description of system calls 2FH-57H includes the following: 


A drawing of the 8086 registers that shows their contents before 


and after the system call. 


A more complete description of the register contents required 


before the system call. 


A description of the processing performed. 
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Error returns from the system call. 


An example of its use. 


Figure 1 is an example of how each system call is described. Function 27H, 
Random Block Read, is shown. 


Call 
AH = 27H 
DS:DX 

Opened FCB 

Xx 

Number of blocks to read 
Return 
AL 

O = Read completed successfully 

1 = EOF 


2 = End of segment 

3 = EOF, partial record 
CX 

Number of blocks read 


Figure 1. Example of System Call Description 


1.4.1 Programming Examples 
A macro is defined for each system call, then used in some examples. In addition, 

a few other macros allows the examples to be more complete programs, rather 
than isolated uses of the system calls. All macro definitions are listed at the end of 
the chapter. 


The examples are not intended to represent good programming practice. In 
particular, error checking and good human interface design have been sacrificed 
to conserve space. You may, however, find the macros a convenient way to 
include system calls in your assembly language programs. 


A detailed description of each system call follows. They are listed in numeric 
order; the interrupts are described first, then the function requests. 


NOTE 


Uniess otherwise stated, all numbers in the 
system call descriptions -- both text and code -- 
are in hex. 
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1.5 XENIX COMPATIBLE CALLS 


Advance DOS supports hierarchical (i.e., tree-structured) directories, similar to 
those found in the Xenix operating system. (For information on tree-structured 
directories, refer to the Advance 86 User’s Guide.) 


The following system calls are compatible with the Xenix system: 


wf 
Ay, 


Function 39H Create Sub-Directory 

Function 3AH Remove a Directory Entry 

Function 3BH Change the Current Directory 
Function 3CH Create a File 

Function 3DH Open a File 
Function 3FH Read from File/Device 

Function 40H Write to a File or Device 

Function 41H Delete a Directory Entry 

Function 42H Move a File Pointer 

Function 43H Change Attributes 

Function 44H |/O Control for Devices 

Function 45H Duplicate a File Handle 

Function 46H Force a Duplicate of a Handle 
Function 4BH Load and Execute a Program 
Function 4CH Terminate a Process 

Function 4DH Retrieve the Retum Code of a Child 


There is no restriction in Advance DOS on the depth of a tree (the length of the 
longest path from root to leaf) except in the number of allocation units available. 
The root directory will have a fixed number of entries (112 for the double-sided 
disk). For non-root directories, the number of files per directory is only limited by 
the number of allocation units available. 

Implementation of the tree structure is simple. The root directory is the fixed 
directory. Subdirectories of the root have a special attribute set indicating that 
they are directories. The subdirectories themselves are files, linked through the 


- FAT as usual. Their contents are identical in character to the contents of the root 


directory. © 
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Attributes apply to the tree-structured directories in the following manner: 


Attribute 


volume_id 


directory 


read__only 


archive 


hidden/ 
system 


Meaning/Function 
for files 


Present at the root. 
Only one file may have 
this set. 


Meaningless. 


Old fcb-create, new 
Create, new open (for 
write or read/write) 
will fail. 


Set when file is 
written. Set/reset via 
Function 43H. 


Prevents file from 
being found in search 
first/search next. 

Old open will fail. 


Meaning/Function 
for directories 


Meaningless. 


Indicates that the 
directory entry is a 
directory. Cannot be 
changed with 43H. 


Meaningless. 


Meaningless. 


Prevents directory 
entry from being 
found. Function 3BH 
will still work. 
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1.6 INTERRUPTS 

Advance DOS reserves interrupts 20H through 3FH for its own use. The table of 
interrupt routine addresses (vectors) is maintained in locations 80H-FCH. Table 
1.3 lists the interrupts in numeric order; Table 1.4 lists the interrupts in alphabetic 
order (of the description). User programs should only issue Interrupts 20H, 21H, 
25H, 26H, and 27H. (Function Requests 4CH and 31H are the preferred method 
for Interrupts 20H and 27H for versions of Advance DOS that are 2.0 and higher.) 


NOTE 


Interrupts 22H, 23H, and 24H are not interrupts 
that can be issued by user programs; they are 
simply locations where a segment and offset 
address are stored. 


Table 1.3 Advance DOS Interrupts, Numeric Order 


Interrupt 

Hex Dec 
20H oe 
21H 33 
22H 34 
ear Cis. 
24H 36 
25H 37 
26H 38 
27H 39 
28-40H 40-64 


Description 


Program Terminate 

Function Request 

Terminate Address 
<CTRL-C> Exit Address 
Fatal Error Abort Address 
Absolute Disk Read 
Absolute Disk Write 
Terminate But Stay Resident 
RESERVED -- DO NOT USE 


Table 1.4 Advance DOS Interrupts, Alphabetic Order 


a 


Interrupt 

Description Hex Dec 
Absolute Disk Read 25H 37 
Absolute Disk Write 26H 38 
<CTRL-C> Exit Address 23H 35 
Fatal Error Abort Address 24H 36 
Function Request 21H 33 
Program Terminate 20H 32 
RESERVED -- DO NOT USE 28-40H 40-64 
Terminate Address 22H 34 


Terminate But Stay Resident 27H 39 


_ Mandan 
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Program Terminate (Interrupt 20H) 


Call 
sets CS 
CX: Segment address of Program Segment 
Prefix 
DX: 
Retum 
None 


Interrupt 20H causes the current process to terminate and retums control to its 
parent process. All open file handles are closed and the disk cache is cleaned. 
This interrupt is almost always used in old .COM files for termination. 


- —_ aes eo —<ae or me 60 Ow ee eres ree OS SS 
—_—— 


The CS register must contain the segment address of the Program Segment 
Prefix before you call this interrupt. 


The following exit addresses are restored from the Program Segment Prefix: 


Exit Address Offset 
Program Terminate OAH 
CONTROL-C OEH 
Critical Error 12H 


All file buffers are flushed to disk. 


NOTE 


Close all files that have changed in length before 
issuing this interrupt. If a changed file is not closed, 
its length is not recorded correctly in the directory. 
See Functions 10H and 3EH for a description of 
the Close File system calls. 


ihe 
232 
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| interrupt 20H is provided for compatibility with versions of Advance DOS prior to 
i 2.0. New programs should use Function Request 4CH, Terminate a Process. 


Macro Definition: terminate macro 


int 20H 
endm 
Example 
-CS must be equal to PSP values given at program start 
(ES andDs values) 
INT 20H 


| {There is noretum from this interrupt 


. 
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Function Request (Interrupt 21H) 


Call 
: : AH 

Function number 
OX: Other registers as specified in 
DX: individual function 


Return 


a ae As specified in individual function 


*@& seca sc ame - =e e-em -G e - © comp - 


The AH register must contain the number of the system function. See Section 1 i 
Function Requests”, fora description of the Advance DOS system funetions. 


NOTE 


No macro is defined for this interrupt, because all 
function descriptions in this chapter that define a 
macro include Interrupt 21H. 


Example , 
To call the Get Time function: 


mov ah 2CH ;Get Time is Function 2CH 
int 21H ‘THIS INTERRUPT 


Pes ie. —— wees 
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Terminate Address. 


Terminate Address (Interrupt 22H) 
CONTROL-C Exit Address (Interrupt 23H) 
Fatal Error Abort Address (interrupt 24H) 


These are not true interrupts, but rather storage locations for a segment and 
offset address. The interrupts are issued by Advance DOS under the specified 
circumstance. You can change any of these addresses with Function Request 
25H (Set Vector) if you prefer to write your own interrupt handlers. 


Interrupt 22H -- Terminate Address 

When a program terminates, control transfers to the address at offset OAH of the 
Program Segment Prefix. This address is copied into the Program Segment 
Prefix, from the Interrupt 22H vector, when the segment is created. 


Interrupt 23H -- CONTROL-C Exit Address 

lf the user types CONTROL-C during keyboard input or display output, control 
transfers to the INT 23H vector in the interrupt table. This address is copied into 
the Program Segment Prefix, from the Interrupt 23H vector, when the segment is 
created. 


lf the CONTROL-C routine preserves all registers, it can end with an IRET 
instruction (retum from interrupt) to continue program execution. When the 
interrupt occurs, all registers are set to the value they had when the original call to 
Advance DOS was made. There are no restrictions on what a CONTROL-C 
handler can do -- including Advance DOS function calls -- so long as the registers 
are unchanged if IRET is used. 


lf Function O9H or OAH (Display String or Buffered Keyboard Input) is interrupted 
by CONTROL-C, the three-byte sequence OS3H-ODH-OAH (ETX-CR-LF) is sent 
to the display and the function resumes at the beginning of the next line. 


lf the program creates a new segment and loads a second program that changes 
the CONTROL-C address, termination of the second program restores the 
CONTROL-C address to its value before execution of the second program. 


_ 
te nr teen 
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Interrupt 24H -- Fatal Error Abort Address 

lf a fatal disk error occurs during execution of one of the disk I/O function calls, 

control transfers to the INT 24H vector in the vector value. This address is copied : 
into the Program Segment Prefix, from the Interrupt 24H vector, when the 

segment Is created. 


BS:SI contains the address of a Device Header Control Block from which 
additional information can be retrieved. 


NOTE 


Interrupt 24H is not issued if the failure occurs 
during execution of Interrupt 25H (Absolute Disk 
Read) or Interrupt 26H (Absolute Disk Write). 
These errors are usually handled by the Advance 
DOS error routine in COMMAND.COM that retries 
the disk operation, then gives the user the choice 
of aborting, retrying the operation, or ignoring the 
error. The following topics give you the information 
you need about interpreting the error codes, 
managing the registers and stack, and controlling 
the system’s response to the error in order to write 
your own error-handling routines. 


Error Codes | 
When an error-handling program gains control from Interrupt 24H, the AX and DI 
registers can contain codes that describe the error. If Bit 7 of AH is 1, the error is 
either a bad image of the File Allocation Table or an error occurred on a character 
device. The device header passed in BP:SI can be examined to determine which 
case exists. If the attribute byte high order bit indicates a block device, then the 
error was a bad FAT. Otherwise, the error is on a character device. 
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The following are error codes for Interrupt 24H: 


Error Code 


OWPrOONoaUNARWN—O 


Description 

Attempt to write on write-protected disk 
Unknown unit 

Drive not ready 

Unknown command 

Data error 

Bad request structure length 
Seek error 

Unknown media type 
Sector not found 

Printer out of paper 

Write fault 

Read fault 

General failure 


The user stack will be in effect (the first item described below is at the top of the 
stack), and will contain the following from top to bottom: 


iP 
CS 


FLAGS 


i? 


Advance DOS registers from 
issuing INT 24H 


User registers at time of original 
INT 21H request 


From the original INT 21H 
CS 


from the user to Advance DOS 
LAGS 


The registers are set such that if an IRET is executed, Advance DOS will respond 
according to (AL) as follows: 


(AL)=0 


1 
2 


ignore the error 
retry the operation 
terminate the program via INT 23H 
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Before giving this routine control for disk errors, Advance DOS 
performs five retries. 


For disk errors, this exitis taken only for errors occurring during an 
Interrupt 21H. It is not used for errors during Interrupts 25H or 
26H. 


This routine is entered ina disabled state. 

The SS, SP, DS, ES, BX, CS, and DX registers must be preserved. 
This interrupt handler should refrain from using Advance DOS 
function calls. If necessary, it may use calls 01H through OCH. 


Use of any other call will destroy the Advance DOS stack and will 
leave Advance DOS in an unpredictable state. 


The interrupt handler must not change the contents of the device 


header. 


if the interrupt handler will handle errors rather than retuming to 
Advance DOS, it should restore the application program's 
registers from the stack, remove all but the last three words on the 
stack, then issue an IRET. This will retum to the program 
immediately after the INT 21H that experienced the error. Note 
that if this is done, Advance DOS will be in an unstable state until a 
tinction call higher than OCH is issued. 


— ane 
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Absolute Disk Read (Interrupt 25H) 


AX: Call 
BX: AL 
CX: Drive number 
Disk Transfer Address 
CX 
Number of sectors 


Beginning relative sector 


Error code if CF=1 
FlagsL 
CF = Oif successful 
= if not successful 


"The registers must contain the following: 


AL ODrive number (O=A, 1=B, etc.). 

BX Offset of Disk Transfer Address 
(from segment address in DS). 

CX Number of sectors to read. 

DX Beginning relative sector. 


This interrupt transfers control to the Advance DOS BIOS. The number of sectors 
specified in CX is read from the disk to Disk Transfer Address. Its requirements 
and processing are identical to Interrupt 26H, except data is read rather than 
written. 


NOTE 


All registers except the segment registers are 
destroyed by this call. Be sure to save any registers 
your program uses before issuing the interrupt. 


The system pushes the flags at the time of the call; they are still there upon return. 
(This is necessary because data is passed back in the flags.) Be sure to pop the 
stack upon retum to prevent uncontrolled growth. 


lf the disk operation was successful, the Carry Flag (CF) is 0. If the disk operation 
was not successful, CF is 1 and AL contains the Advance DOS error code (see 
Interrupt 24H earlier in this section for the codes and their meaning). 


BV 
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Macro Definition: 


abs__disk_read macro disk,buffer,num__sectors,start 
mov al disk 
mov bx, offset buffer 


mov “-7™™ 41 sectors 

Mov dhs 

int 25! 

endn O I< ; 


Example 


The following program copies the contents of a single-sided disk in drive A: to the 
disk in drive B:. It uses a buffer of 32K bytes: 


prompt db “Source in A, targetinB’,13,10 | 
db, “Any key to start. $” 

Start dw 0 

buffer db 64dup(512dup(?)) :64 sectors 


int_25H: display prompt see Function 09H 
read__kbd see Function 08H 
mov Cx,5 ;Copy 5 groups of 
(64 sectors 
Copy: push CX save the loop counter 


aDs__disk_read 0O,buffer,64,start :THIS INTERRUPT 
abds__disk__write 1,butfer,64 start ‘see int 26H 


add start,64 ;do the next 64 sectors 
pop cx restore the loop counter 
loop copy 


. see . -. a 
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Absolute Disk Write (Interrupt 26H) 


Drive number 
DS:BxX | 
Disk Transfer Address 
CX 
Number of sectors 
DX 


Beginning relative sector 


Error code if CF = 1 
FLAGSL 
CF = Oif successful 
1 if not successful 


The registers must contain the following: 


Drive number (O=A, 1=8, etc.). 
Offset by Disk Transfer Address 
(from segment address in DS). 
Number of sectors to write. 
Beginning relative sector. 
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This interrupt transfers control to the Advance DOS BIOS. The number of sectors 
specified in CX is written from the Disk Transfer Address to the disk. Its 
requirements and processing are.identical to Interrupt 25H, except data is written 
to the disk rather than read from it. 


NOTE 


All registers except the segment registers are 
destroyed by this call. Be sure to save any 
registers your program uses before issuing the 


The system pushes the flags at the time of the call; they are still there upon retum. 
(This is necessary because data is passed back in the flags.) Be sure to pop the 
stack upon retum to prevent uncontrolled growth. 


If the disk operation was successful, the Carry Flag (CF) is 0. If the disk operation 
was not successful, CF is 1 and AL contains the Advance DOS error code (see 
Interrupt 24H for the codes and their meaning). 


(DOB 


ay" 
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abs__disk__write macro 


Example 


The following Program co 
disk in drive B:, verifying 
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MOV 


mov 


mov 
mov 
int 
endm 


disk, buffer,ynum__sectors, start 
al,disk 

bx, offset buffer 
Cx,num__sectors 

dh,start 

26H 


Pies the contents of a Single-sided disk in drive A: to the 
each write. It uses a buffer of 32K bytes: 


“Source in A, target in B13, 10 


Off equ 0 
on equ 1 
Prompt db 

db 
Start dw 


“Any key to start. $” 
0 


buffer db 64 dup (512 dup (?)) ;64 sectors 
INt__26H: display prompt see Function 09H 
read__kbd See Function 08H 
verify on see Function 2EH 
mov cx,5 :;COPy 5 groups of 64 sectors 
copy: push cx Save the loop counter 


aDbs__disk__read O,buffer,64,start see INT 25H 
abs__disk__write 1,buffer,64 start -THIS INTERRUPT 
add start,64 ;do the next 64 sectors 

Pop cx 


loop copy 


verify off 


restore the loop counter 


see Function 2EH 


a ee nn ee en re ee es — = 
anes oa) ane . 


. 
Tr me ee ee ee | ee ee et. em a ~ PRED. © AREAS GSES a _ 
— a - ~~... <2 _ -- ° 
- 


! 


| 


P BV 
Wis 
ae 


Chapter One Systems Calls Page 1-23 


Terminate But Stay Resident (Interrupt 27H) 


First byte following 
last byte of code 


Return 
None 


The Terminate But Stay Resident call is used to make a piece of code remain 
resident in the system after its termination. Typically, this call is used in .COM files 
to allow some device-specific interrupt handler to remain resident to process 
asynchronous interrupts. 


DX must contain the offset (from the segment address in CS) of the first byte 
following the last byte of code in the program. When Interrupt 27H is executed, 
the program terminates but is treated as an extension of Advance DOS; it 
remains resident and is not overlaid by other programs when it terminates. 


This interrupt is provided for compatibility with versions of Advance DOS prior to 
2.0. New programs should use Function 31H, Keep Process. 


Macro Definition: stay__resident macro last__instruc 
mov  dx,offset last_instruc 


inc dx 
int 27H 
endm | 
Example 
‘CS must be equal to PSP values given at program start 
‘(ES and DS values) 
mov DX,LastAddress 
int 27H 


‘There is no retum from this interrupt 


i — = 
Bits 
Ste) 
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1.7 FUNCTION REQUESTS 

Most of the Advance DOS function calls require input to be passed to them in 
registers. After setting the proper register values, the function may be invoked in 
one of the following ways: 


1. Place the function number in AH and execute a long call to offset 
50H in your Program Segment Prefix. Note that programs using 
this method will not operate correctly on versions of Advance 
DOS that are lower than 2.0. 


2. Place the function number in AH and issue Interrupt 21H. All of the 
examples in this chapter use this method. 


3. An additional method exists for programs that were written with 
different calling conventions. This method should be avoided for 
all new programs. The function number is placed in the CL register 
and other registers are set according to the function specification. 
Then, as intrasegment call is made to location 5 in the current 
code segment. That location contains a long call to the Advance 
DOS function dispatcher. Register AX is always destroyed if this 
method is used; otherwise, it is the same as normal function calls. 
Note that this method is valid only for Function Requests OOH 
through 024H. 


1.7.1 CP/M® — Compatible Calling Sequence 
A different sequence can be used for programs that must conform to CP/M calling 
conventions: 


1. Move any required data into the appropriate registers (just as in 
the standard sequence). ; 


Move the function number into the CL register. 


Execute an intrasegment call to location 5 in the current code 
segment. 


This method can only be used with functions OOH through 24H that do not pass a 
parameter in AL. Register AX is always destroyed when a function is called in this 
manner. 
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1.7.2 Treatment Of Registers 
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When Advance DOS takes control after a function call, it switches to an internal 


stack. Registers not used to return information (except AX) are preserved. The 
calling program’s stack must be large enough to accommodate the interrupt 


system -- at least 128 bytes in addition to other needs. 


Table 1.5 Advance DOS Function Requests, Numeric Order 


Function 
Number 


OOH 
01H 
02H 
03H 
04H 
O5H 
O6H 
07H 
08H 
OSH 
OAH 
OBH 
OCH 
ODH 
OEH 
OFH 
10H 


1TH: 


12H 
13H 
14H 
15H 
16H 
17H 
19H 
1AH 


IMPORTANT NOTE 


The macro definitions and extended example for 
Advance DOS system calls OOH through 2EH can 
be found at the end of this chapter. 


Table 1.5 lists the function requests in numeric order; 


Function Name 


Termination 

Read Keyboard and Echo 
Display Character 
Auxiliary Input 

Auxiliary Output 

Print Character 

Direct Console I/O 

Direct Console Input 
Read Keyboard 

Display String 

Buffered Keyboard Input 
Check Keyboard Status 
Fiush Buffer, Read Keyboard 
Disk Reset 

Select Disk 

Open File 

Close File 

Search for First Entry 
Search for Next Entry 
Delete File 

Sequential Read 
Sequential Write 

Create File 

Rename File 

Current Disk 
Set Disk Transfer Address 


Table 1.6 list the function requests in alphabetic order (of the description). 
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21H Random Read 
22H Randon Write 
23H File Size 
24H Set Relative Record 
225A Set Vector 
27H Random Block Read 
28H Random Block Write 
29H Parse File Name 
2AH Get Date 
2BH Set Date 
2CH Get Time 
2DH Set Time 
2eH - Set/Reset Verify Flag 
2FH Get Disk Transfer Address 
30H Get DOS Version Number N 
ah Keep Process 
33H CONTROL-C Check L Sean es clhan ec. ww 
oor Get Interrupt Vector 34 | Oe | 2 
36H Get Disk Free Space --? 
38H Return Country-Dependent Information 
39H Create Sub-Directory 
3AH Remove a Directory Entry 
3BH Change Current Directory 
3CH Create a File 
30h Open a File 
3Eh Close a File Handle 
oP Read From File/Device 
40H Write to a File/Device 
41H Delete a Directory Entry 
42H -Move a File Pointer 
43H Change Attributes 
44H {/O Control for Devices 
45H Duplicate a File Handle 
46H ~ Force a Duplicate of a Handle 
47H Return Text of Current Directory 
48H Allocate Memory 
49H Free Allocated Memory 
4BH Load and Execute a Program 
4CH Terminate a Process 
4DH Retrieve the Return Code of a Child 
4EH Find Match File 
4FH Step Through a Directory Matching Files 
54H Return Current Setting of Verify 
56H Move a Directory Entry 


57H Get/Set Date/Time of File 


- ee ee wee 
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Table 1.6 Advance DOS Function Requests, Alphabetic Order 


Function Name 


Allocate Memory 
Auxiliary Input 

Auxiliary Output 

Buffered Keyboard Input 
Change Attributes 
Change the Current Directory 
Check Keyboard Status 
Close a File Handle 

Close File 

CONTROL-C Check 
create a File 

Create File 

Create Sub-Directory 
Current Disk 

Delete a Directory Entry 
Delete File 

Direct Console Input 
‘Direct Console I/O 

Disk Reset 

Display Character 

Display String 

Duplicate a File Handle 
File Size 

Find Match File 

Flush Buffer, Read Keyboard 
Force a Duplicate of a Handle 
Free Allocated Memory 
Get Date 

Get Disk Free Space 

Get Disk Transfer Address 
Get DOS Version Number 
Get Interrupt Vector 

Get Time 

Get/Set Date/Time of File 
I/O Control for Devices 


~ Keep Process 


Load and Execute a Program 
Modify Allocated Memory Blocks 
Move a Directory Entry 

Move a File Pointer 

Open a File 

Open File 

Parse a File Name 

Print Character 

Random Block Read 
Random Block Write 
Random Read 

Random Write 

Read From File/Device 
Read Keyboard 
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Number 


48H 
03H 
04H 
OAH 
43H 
3BH 
OBH 
SEH 
10H 
33H. 
3CH 
16H 
39H 
19H 
41H 
13H 
07H 
O6H 
ODH 
02H 
O9H 
45H 
23H 
4EH 
OCH 
46H 
49H 
2AH 
36H 
aro 
30H 
35H 
2CH 
s7Fi 
44H 


31H - 


4BH 
4AH 
56H 
42H 
3DH 
OFH 
29H 
OSH 
27H 
28H 
21H 
22H 
3FH 
08H 


WY 
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Read Keyboard and Echo 01H 
Remove a Directory Entry 3AH 
Rename File 17H 
Retrieve the Return Code of a Child 4DH 
Returm Current Setting of Verify 54H 
Return Country-Dependent Information 38H 
Return Text of Current Directory 47H 
Search for First Entry 11H 
Search for Next Entry 12H 
Select Disk OEH 
Sequential Read 14H 
Sequential Write 158 
Set Date 2BH 
Set Disk Transfer Address 1AH 
Set Relative Record 24H 
Set Time 2DH 
Set Vector 25H 
Set/Reset Verify Flag 2EH 
Step Through a Directory Matching 4FH 
Terminate a Process 4CH 
Terminate Program OOH 
40H 


Write to a File/Device 
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Terminate Program (Function 00H) 


Call 
AH = 00H 
CS 
Segment address of 


Program Segment Prefix 


Return 
None 


~ Function OOH is called by Interrupt 20H; it performs the same processing. 


The CS register must contain the segment address of the Program Segment 
Prefix before you call this interrupt. 


The following exit addresses are restored from the specified offsets in the 
Program Segment Prefix: 


Program terminate OAH 
CONTROL-C OER 
Critical error 12H 


All file buffers are flushed to disk. 

Waming: Close all files that have changed in length before calling this function. If 
a changed file is not closed, its length is not recorded correctly in the directory. 
See Function 10H for a description of the Close File system call. 


Macro Definition. terminate__program macro 


xor ah,ah 
int 21H 
endm 
Example 
‘CS must be equal to PSP values given at program start 
‘(ES and DS values) 
mov ah 0 
int 21H 


‘There are no retums from this interrupt 


|) ee 
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Read Keyboard and Echo (Function 01H) 


Call 
AH = 01H 
Return 
AL 
Character typed 
BP. 
= ae 
a: ae 


Function 01H waits for a character to be typed at the keyboard, then echoes the 
character to the display and returns it in AL. If the character is CONTROL-C, 
Interrupt 23H is executed. 


Macro Definition: read__kbd__and__echo macro 
mov ah,01H 
int 21H 
endm 


Example 


The following program both displays and prints characters as they are typed. If 
RETURN is pressed, the program sends Line Feed-Carriage Return to both the 
display and the printer:. 


func_01H: read_kbd__and__echo sTHIS FUNCTION 
print_char al ‘see Function 05H 
cmp al,ODH ‘is ita CR? 
jne func__01H sno, print it 
print_char 10 ;see Function OSH 
display__char 10 ‘see Function 02H 


jmp func_.01H ;get another character 


2S | 
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Display Character (Function 02H) 


AX: Call 
BX: AH = 02H 
CX: DL 
Dx: Character to be displayed 
SP Return 
None 


_ Function 02H displays the character in DL. If CONTROL-C is typed, Interrupt 23H 
is issued. 


Macro Definition: display_.charmacro character 
mov di,character 


mov ah,02H 
int 21H 
endm 


Example 


' The following program converts lowercase characters to uppercase before 
displaying them: 


func__02H: read__kbd ‘see Function 08H 


cmp al,‘‘a”’ 
jl uppercase ;don’t convert 
cmp al.“2" 
jg uppercase ;don’t convert 
sub al,20H convert to ASCII code 
‘for uppercase 
uppercase: display__charal >THIS FUNCTION 


jmp func 02H: ;get another character 
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Auxiliary Input (Function 03H) 


Call 

AH = 03H 
Return 

AL 


Function 03H waits for a character from the auxiliary input device, then returns 
the character in AL. This system call does not return a status or error code. 


lf a CONTROL-C has been typed at console input, Interrupt 23H is issued. 


Macro Definition: aux__input macro 
mov ah,03H 
int 21H 
endm 


Example 


The following program prints characters as they are received from the auxiliary 
device. It stops printing when an end-of-file character (ASCII 26, or CONTROL- 
Z) is received: 


func__.03H: aux_input ‘THIS FUNCTION 
cmp al,1AH ;end of file? 
je continue ‘yes, all done 
print_char al see Function OSH © 
imp  func__03H ;get another character 


continue: 


i 
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Auxiliary Output (Function 04H) 


AX: 
BX: 
CX: 
DX: 


Function 04H sends the character in DL to the auxiliary output device. This 
system call does not return a status or error code. 


lfa CONTROL-C has been typed at con 


id Retum 
None 


Character for auxiliary device 


_ na 
_— -.-—— ana. & 


sole input, Interrupt 23H is issued. 
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Macro Definition: aux__output macro character 
mov di,character 


Example 


mov ah,04H 
int 21H 
endm 


The following program gets a series of strings of up to 80 bytes from the keyboard, - 
sending each to the auxiliary device. It stops when a null string (CR only) is typed: 


string 


func__04H: 


send_it: 


continue: 


db 


get_string 80,string 

cmp string[1],0 

je continue 

mov cx, word ptr string[1] 
mov bx,0 

aux__output string[bx+2] 
inc bx 

loop send_it 

jmp = func__04H 


81 dup(?) ;see Function OAH 


“see Function OAH 

null string? 

‘yes, all done 

get string length 

set index to 0 

‘THIS FUNCTION 
‘bump index 

;send another character 
;get another string 
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Print Character (Function 05H) 


AX: 
Bx: 
Ce: 
x. 


Character for printer 


S Return 


None 


Function 05H prints the character in DL on the standard printer device. If 
CONTROL-C has been typed at console input, Interrupt 23H is issued. 


Macro Definition: 


Example 


print__char macro character 


mov di,character 
mov ah,05H 

int 21H 

endm 


The following program prints a walking test pattern on the printer. It stops if 
CONTROL-C is pressed. 


line__num 


func... OSt3: 
Start__line: 


print_it: 


no__reset: 


mov c¢x.60 


sprint 60 lines 
mov 61,33 ‘first printable ASCII 
‘character (!) 
add __ Di, line__num ‘to offset one character 
push cx ‘Save number-of-lines counter 
mov cx,80 ‘loop counter for line 
print_char bl ‘THIS FUNCTION 
inc bl ‘move to next ASCII character 
cmp 1,126. ‘last printable ASCII 
‘character (7) 
i! - NO__reset snot there yet 
mov b1,33 ‘Start over with (!) 
loop print__it ‘print another character 
print_char 13 ‘Carriage return 
print_char 10 line feed 
inc =‘ line__num ‘to offset 1st char. of line 
pop cx ‘restore # -of-lines counter 


loop’ Start__ne: 


sprint another line 


ayy? EE 
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Direct Console I/O (Function 06H) 


Retum 


if DL = FFH (255) before call, 
then Zero flag set means AL has character from 


keyboard. 
Zero flag not set means there was 
not a character to get, and AL = 0. 


—_ —eo 


The processing depends on the value in DL when the function is called: 
DL is FFH (255) - If a character has been typed at the keyboard, 
it is returned in AL and the Zero flag is 0; if a character has not 
been typed, the Zero flag is 1. 


DL is not FFH -- The character in DL is displayed. 


This function does not check for CONTROL-C. 


Macro Definition: dir__console_io macro switch 
mov di, switch 


mov ah,06H 
int 21H 
~endm 


7 eee eee ee eee 

ee 

ee 

a 
ee ee ee 


a 
aes 
25 | 
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Example 


The following program sets the system clock to 0 and continuously displays the 
time. When any character is typed, the display stops changing; when any 
character is typed again, the clock is reset to 0 and the display starts again: © 


time db ‘00:00:00.00",13,10,"$" ;see Function OSH 

‘for explanation of S 

ten db 10 

func__06H: set_me 0,0,0,0 -see Function 2DH 

read__clock: get_time -see Function 2CH 
convert ch,ten,time ‘see end of chapter 
convert _ cl,ten,time[3] ‘see end of chapter 
convert dh,ten,time(6] ‘see end of chapter 
convert di,ten,time(9] ‘see end of chapter 
display time ‘see Function 09H 
dir__console__io FFH ‘THIS FUNCTION 
jne stop ‘yes, Stop timer 
imp read__clock ‘no, keep timer 

‘running 
stop: read__kbd ‘see Function 08H 


jmp func__O6H ‘start over 
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Direct Console Input (Function 07H) 


AX: Call 
BX: AH = 07H 
Ga 
DX: Return 
AL 
Character from keyboard 
SS: ae 
ae 


woe eee eee 


Function 07H waits for a character to be typed, then returns it in AL. This function 
does not echo the character or check for CONTROL-C. (For a keyboard input 
function that echoes or checks for CONTROL-C, see Functions 01H or 08H). 


Macro Definition: dir_cconsole__input macro 
mov ah,07H 
int 21H 
endm 


Example 


The following program prompts for a password (8 characters maximum) and 
places the characters into a string without echoing them: 


password ‘db 8 dup(?) | 
prompt db “Password: $” see Function O9H for 
‘explanation of $ 
func__07H: display prompt ‘see Function 09H 
mov cx,8 ‘maximum length of password 
xor bx,bx ‘So BL can be used as index 
get_pass: dir__cconsole__input sTHIS FUNCTION 
cmp al,ODH ‘was it a CR? 
je continue ‘yes, all done 
mov password[bx],al no, put character in string 
inc bx ‘bump index 
loop get__pass ‘get another character 
_ continue: ; ;BX has length of password + 1 


ax 
45ST 
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Read — (Function 08H) 


a 
AX: Call aN" 
BX: AH = 08H 
CX: 
ne Return 
AL 
P Character from keyboard . 


Function O8H waits for a character to be typed, then retums it in AL. If CONTROL-C 
is pressed, Interrupt 23H is executed. This function does not echo the character. 
(For a keyboard input function that echoes the character or checks for 
CONTROL-C, see Functions 01H.) 


Macro Definition: read__kbd macro 
mov ah,08H 
int 21H 
endm 


Example 


The following program prompts for a password (8 characters maximum) and 
places the characters into a string without echoing them: 


password db 8dup(?) 


prompt db “Password: $” ‘See Function 09H 
‘for explanation of $ 
func__08H: display prompt ‘see Function 09H 
mov cx,8 ‘maximum length of password 
xor bx,bx ‘BL can be an index 
get_pass: read__kbd sTHIS FUNCTION 
cmp al,0ODH ‘was it a CR? 
je continue ‘yes, all done 
mov password[bx],al No, put char. in string 
inc bx ‘bump index 
loop get__pass ‘get another character 


continue: : ;BX has length of password+1 


e ob Paap ee = == Oe wee eg” 
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y String (Function 09H) 7 ; bas 

7 e. 
Call eC 
AH = 09H 
DS:DX 

String to be displayed 

Return 
None 


-_ Dx must contain the offset (from the segment address in DS) of a string that ends 
with ‘‘$’’. The string is displayed (the $ is not displayed). 


ee ee eee oe mee 


Macro Definition: display macro string 
mov  dx,offset string 


mov ah,O9H 
int 21H 
endm 
Example 
The following program displays the hexadecimal code of the key that is typed: 
table db “0123456789ABCDEF” 
sixteen db 16 
result db * —_— OOH’, 13,10,‘'$” ‘see text for 
‘explanation of $ 
func__O9H: read_kbd*_and__echo ‘see Function 01H 
convert al,sixteen,result(3] ‘see end of chapter 
display result ' THIS FUNCTION 


jmp —_ func__09H ‘do it again 
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Buffered Keyboard Input (Function 0AH) 


Ax: FooRpoe Call 


Bx AH = OAH 
Cx DS:DX 
Ox: Input buffer 
Return 
None 


DX must contain the offset (from the segment address in DS) of an input buffer of 
the following form: : 


Byte Contents 


1 Maximum number of characters in buffer, including the CR (you must set 
this value). 
Z Actual number of characters typed, not counting the CR (the function 


sets this value). 
3-n Buffer; must be at least as long as the number in byte 1. 


This function waits for characters to be typed. Characters are read from the 
keyboard and placed in the buffer beginning at the third byte until RETURN is 
typed. If the buffer fills to one less than the maximum, additional characters typed 
are ignored and ASCII 7 (BEL) is sent to the display until RETURN is pressed. 
The string can be edited as it is being entered. If CONTROL-C is typed, Interrupt 
23H is issued. 


The second byte of the buffer is set to the number of characters entered (not 
counting the CR). 


Macro Definition: get__string macro limit,string 
mov  dx,offset string 
mov _ string,limit 
mov ah,O0AH 
int 21H 
endm 


ee a ee ee 
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Example 


Systems Calls 


The following program gets a 16-byte (maximum) string from the keyboard and 
fills a 24-line by 80-character screen with it: 


buffer 
max__liength 
chars__entered 
string 
strings__per__line 
crif 

func__OAH: 


‘display__screen: 


display__line: 


label byte 
db ? 
db ? 
db 17 dup(?) 
dw QO 


db 13,10,” 


get__string 17, buffer 
xor bx,bx 


mov bli,chars__entered 
mov buffer[bx+2],°‘$” 
mov al,50H 

cow 

div chars__entered 


xor ah,ah 

mov strings__per__line,ax 
mov cx,24 

push cx 

mov cx,strings__per__line 
display string 

loop display__line 

display crif 

Pop Cx 

loop display__screen 


‘maximum length 
‘number of chars. 
16 chars + CR 
-how many strings 
‘fit on line 


‘THIS FUNCTION 
So byte can be 


ra fr 
‘times string fits 
‘on line ) 
‘clear remainder 
‘save col. counter a 2 


row counter 
sa 


‘save it P 
‘get col. counter 
“see Function 09H 


‘see Function 09H 
‘get line counter 
‘display 1 more line 


ose 88 St eee Sree cormems. comms TO ae ceerews om er eee. ee Cet SS ER we ee ee. one 
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Check Keyboard Status (Function 0BH) 


Call 

AH = OBH 

Retum 

AL 
255 (FFH) = characters in type-ahead 
a: ae buffer 
0 = no characters in type-ahead 
[or buffer 


ee OS ee - oe... 
° as am ee -— 


Checks whether there are characters in the type-ahead buffer. If so, AL retums 
FFH (255); if not, AL retums 0. If CONTROL-C is in the buffer, Interrupt 23H is 
executed. 


Macro Definition: check__kbd__status macro 
mov ah,oBH 
int 21H 
endm 


Example 


The following program continuously displays the time until any key is pressed. 


time db "00:00:00.00";13,10,"S" 

ten db 10 

func_OBH: gettime ‘see Function 2CH 
convert ch,ten,time see end of chapter 
convert cli,ten,time(3] ‘see end of chapter 
convert dh,ten,time[6] ‘see end of chapter 
convert di,ten,time[9] see end of chapter 
display time ‘see Function 09H 
check__kbd__status ‘THIS FUNCTION 
cmp al,FFH ‘has a key been typed? 
je all__done “yes, go home 


imp — func__OBH "no, keep displaying time 


e ~- ae + —@ebeam amp wees: +e) + GE Seas oo eas ocoo-mere 
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Qior 


1,6, 7, 8, otOAH = The 
corresponding function 
is called. 

Any other value = no 
further processing. 


Return 

AL 
O = Type-ahead buffer was 
flushed; no other 
processing performed. 


The keyboard type-ahead buffer is emptied. Further processing depends on the 
value in AL when the function is called: | 


1, 6, 7, 8, or OAH -- The corresponding Advance DOS function is 
executed. 


Any other value -- No further processing; AL returns 0. 


Macro Definition: flush__and__read__kbd macro switch 


Example ; 


mov. al,switch 
mov ah,OCH 
int 21H 
endm 


The following program both displays and prints characters as they are typed. If 
RETURN is pressed, the program sends Carriage Return-Line Feed to both the 


display and the printer. 

func__OCH: flush_and__read__kbd 1 STHIS FUNCTION 
print_char al see Function OSH 
cmp al,oDH ‘is ita CR? 
jne func_.OCH sno, print it 
print_char 10 ‘see Function 05H 
display__char 10 see Function 02H 


jmp func_.OCH ;get another character 


i TS 


= 
Aare , 
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Disk Reset (Function O0DH) 


Call 
AH = 0DH 


Return 
None 


Function ODH is used to ensure that the internal buffer cache matches the disks in 
the drives. This function writes out dirty buffers (buffers that have been modified), 
and marks all buffers in the internal cache as free. 


Function ODH flushes all file buffers. It does not update directory entries; you must 
close files that have changed to update their directory entries (see Function 10H, 
Close File). This function need not be called before a disk change if all files that 
changed were closed. It is generally used to force a known state of the system; 
CONTROL-C interrupt handlers should cail this function. 


Macro Definition: disk__reset macro disk 


mov ah,0DH 
int 21H 
endm 
Example 
mov ah,ODH 
int 21H 


‘There are no errors returned by this call. 


CS 
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Bue 
Select Disk (Function O0EH) 
Call 
AH = OEH 
Di 


Drive number 
(0 =A; 1 =B, etc.) 


Number of logical drives 


The drive specified in DL (0 = B;, etc.) is selected as the default disk. The number 


of drives is returned in AL. 


Macro Definition: select__disk macro disk . 
mov di,disk[—64] 
mov ah,0EH 
int 21H 
endm 


Example 


The following program selects the drive not currently selected in a 2-drive 
system: | 


func_.OEH: current__disk see Function 19H 
cmp _ al,OOH ‘drive A: selected? 
je select__b ‘yes, select B 
select__disk ‘“‘A”’ ‘THIS FUNCTION 
jmp continue 

select_b: -select_disk ‘‘B” STHIS FUNCTION 


continue: 


ta 
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Open File (Function OFH) 
AX: Call 
Bx: AH = OFH 
Cx: DS:DX: Unopened FCB 
DX: 

Retum 

AL 


0 = Directory entry found 
255 (FFH) = Nodirectory entry found 


ee me we ee es ee ee ae ee _—_— - ~~ = 


DX must contain the offset (from the segment address in DS) of an unopened File 
Control Block (FCB). The disk directory is searched for the named file. 


If a directory entry for the file is found, AL returns 0 and the FCBis filled as follows: 


lf the drive code was 0 (default disk), it is changed to the actual 
disk used (1 = A;, 2 = B;, etc.). This lets you change the default 
disk without interfering with subsequent operations on this file. 


The Current Block field (offset OCH) is set to zero. 


The Record Size (offset OEH) is set to the system default of 
128. 


The File Size (offset 10H), Date of Last Write (offset 14H), and 
Time of Last Write (offset 16H) are set from the directory entry. 


Before performing a sequential disk operation on the file, you must set the 
Current Record field (offset 20H). Before performing a random disk operation on 
the file, you must set the Relative Record field (offset 21H). If the default record 
size (128 bytes) is not correct, set it to the correct length. 


If a directory entry for the file is not found, AL returns FFH (255). 
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Macro Definition: open macro fcb [ae 
mov dx,offset fcb % 
mov ah,0FH Ze 
int 21H 
endm 


Example 


The following program prints the file named TEXTFILE.ASC that is on the disk in 
drive B:. lf a partial record is in the buffer at end-of-file, the routine that prints the 
partial record prints characters until it encounters an end-of-file mark (ASCII 26, 
or CONTROL-Z): 


feb db 2,°TEXTFILEASC” 
db 25dup(?) 


buffer db 128 dup (7) 
func_OFH: set __dta buffer see Function 1AH 
open fcb ‘THIS FUNCTION 
read__line: read__seq fcb see Function 14H 
cmp al,02H end of file? 
je all__done yes, go home 
cmp al,OOH ;more to come? 
jg check__more sno, check for partial 
record 
mov cx,128 ‘yes, print the buffer 
xor___ Si, Si set index to 0 
print_it: print__char buffer(si] see Function OSH 
inc si ‘bump index 
loop = print_it ;print next character 
jmp  read__line read another record 


check_more:cmp  al,03H 


jne = all__done 


;part. record to print? 
no 


mov cx,128 “yes, print it 
xor _ Si, Si ‘set index to 0 
find_eof: cmp buffer[si],26 ;end-of-file mark? 
ie all__done ‘yes . 
print__char buffer{si] see Function 05H : 
;inc si: ;-bump index to next | 
;character ! 
loop find__eof | 
all_done: close fcb see Function 10H | 


— +) 
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Close File (Function 10H) 


Call 

AH = 10H 

DS:DX 
Opened FCB 


O = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (to the segment address in DS) of an opened FCB. 
The disk directory is searched for the file named in the FCB. This function must be 
called after a file is changed to update the directory entry. 


lf a directory entry for the file is found, the location of the file is compared with the 
corresponding entries in the FCB. The directory entry is updated, if necessary, to 
match the FCB, and AL retums 0. 


lf a directory entry for the file is not found, AL returns FFH (255). 


Macro Definition: close macro fcb 
mov dx,offset fcb 
mov ah,10H 
int 21H 
endm 


Example 


The following program checks the first byte of the file named MOD1.BAS in 
drive B: to see if it is FFH, and prints a message if it is: 


message db ‘Not saved in ASCII format’’,13,10,‘‘S"’ 


feb db 2,“MOD1 BAS” 
db 25 dup(?) 

buffer db 128 dup (7) 

func__10F: set__dta buffer ‘see Function 1AH 
open fcb ‘see Function OFH 


read__seq fcb ;see Function 14H 
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cmp buffer,-FFH 

jne all_done 

display message 
all_done: close fcb 


Is first byte FFH? 
"no 

‘see Function 09H 
>THIS FUNCTION 


— SS came sommes a > emo memes wo 
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Search for First Entry (Function 11H) 


AX: Call 

BX: AH = 11H 

CX: DS:DX 

Dx: Unopened FCB 
Return 


0 = Directory entry found 
FFH (255) = No bast entry found 


DX must contain the offset (from the segment address in DS) of an unopened 
FCB. The disk directory is searched for the first matching name. The name can .- 
have the ? wild card character to match any character. To search for hidden or 
system files, DX must point to the first byte of the extended FCB prefix. 


lf a directory entry for the filename in the FCB is found, AL returns 0 and an 
unopened FCB of the same type (normal or extended) is created at the Disk 
Transfer Address. 


lf a directory entry for the filename in the FCB is not found, AL retums FFH (255). 


Notes: 
lf an extended FCB is used, the following search pattem is used: 


1. If the FCB attribute is zero only normai file entries are inal 
Entries for volume label, sub-directories, hidden, and system files 
will not be returned. 


2. If the attribute field is set for hidden or system files, or directory 
entries, it is to be considered as an inclusive search. All normal file 
entries plus all entries matching the specified attributes are 
retumed. To look at all directory entries except the volume label, _ 
the attribute byte may be set to hidden + system + directory (all 
3 bits on). 


—- OS ee ree mr a pe ee me ree + me ere ers oe se ee er ew ye ee 2 
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3. — If the attribute field is set for the volume label, it is considered an 
exclusive search, and only the volume label entry is returned. 


Macro Definition: search__first macro feb 
mov dx,offset feb 
mov ah,11H 
int 21H 
endm 


Example 


The following program verifies the existence of a file named REPORT.ASM on 
the disk in drive B:: 


yes db “FILE EXISTS.$” 
no db “FILE DOES NOT EXIST.$” 
fob db 2,“REPORT ASM” 
db 25 dup (?) 
buffer db 128 dup (7?) 
func__11H: set __dta buffer ‘see Function 1AH 
search__first fcb sTHIS FUNCTION 
cmp al,FFH ‘directory entry found? 
je not__there no 
display yes ‘see Function 09H 
jmp continue 
not_there: display no ‘see Function 09H 


continue: display crif see Function 09H 


ae some = 


oe) 
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Chapter One Systems Calls Page 1-52 [See *, 


ao 
Search for Next Entry (Function 12H) LARK 


Call 315 


AH = 12H 
DS:DX 
Unopened FCB 


Return 
AL | 
0 = Directory entry found 
FFH (255) = No directory entry found 


—esee 2 
ee 0 ee ee ee ee il 


DX must contain the offset (from the segment address in DS) of an FCB previously 
specified in a call to Function 11H. Function 12H is used after Function 11H 
(Search for First Entry) to find additional directory entries that match a filename 
' that contains wild card’ characters. The disk directory is searched for the next 
‘ matching name. The name can have the ? wild card character to match any 
\ character. To search for hidden or system files, DX must point to the first byte of 
the extended FCB prefix. 


| | 
L lf a directory entry for the filename in the FCB is found. AL retums 0 and an 
unopened FCB of the same type (normal or extended) is created at the Disk 


Transfer Address. i 
li 
lf a directory entry for the filename in the FCB is not found, AL returns FFH (255). 
Macro Definition: search__next macro feb \ a QO 
mov dx,offset fcb 
mov ah,12H “Quy 
int 21H jie at 
endm \ 
E> 
Th Example 
ae The following program displays the number of files on the disk in drive B: 
file message db “Nofiles’,10,13,"$” 
ter files db 0O 
feb ten db 10 
fcb 'e | 9 me” Olan’ at a8 a ak a al a at a a a 
buf db 25 dup(?) 


buffer db 128 dup (7) 


Chapter One 


| 
| 
func__12H: 


search__dir: 


| done: 
| all__done: 
| 
| 
| 
| 
| 
| 
| 
| ; 
| 
| 
| , 
| ; 
| 
| 
| 
| 
! 
: 
| 
| 
| 
_—a 
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set__dta buffer 
search__first feb 
cmp _— al,FFH 
je all__done 
inc files 


search__next fcb 


cmp _ al,FFH 
je done 
inc files 


jmp search__dir 
convert files, ten,message 
display message 
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‘see Function 1AH 
see Function 11H 
‘directory entry found? 
No, no files on disk 
‘yes, increment file 
;counter 

sTHIS FUNCTION 
‘directory entry found? 
"no 

“yes, increment file 
;counter 

;check again 

;see end of chapter 
‘see Function OSH 
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Delete File (Function 13H) 


Call 

AH = 13H 

DS:DX 
Unopened FCB 


Return 
0 = Directory entry found 
FFH (255) = No directory entry found 


DX must contain the offset (from the segment address in DS) of an unopened 
FCB. The directory is searched for a matching filename. The filename in the FCB 
can contain the ? wild card character to match any character. 


lf a matching directory entry is found, it is deleted from the directory. If the ? wild 
card character is used in the filename, all matching directory entries are deleted. 
AL returns 0. 


If no matching directory entry is found, AL returns FFH (255). 


Macro Definition: delete macro fcb 
mov dx,offset feb 
mov ah,13H 
int 21H 
endm 


Example 


The following program deletes each file on the disk in drive B: that was last written 
before December 31, 1982: 


year dw 1982 

month db 12 

day dd 31 

files db 0 

ten db 10 

message Gb “NOFILES DELETED.”,13,10,"$” 
“see Function 09H for 
;explanation of $ 

fob a 2° Cr reer re?” 


db 25dup(?) 


jf? 
Ve 
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buffer 
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db 128 dup (7?) 


func__13H: set__dta buffer 


compare: 


next: 


all__done: 


search__first feb 
cmp alfFt ¢ EH 
je all__done 
convert__date buffer 
cmp cx,year 

fe) next 

cmp di,month 

ie next 

cmp _ dh,day 

jge next 

delete buffer 

inc files 


search__next fcb 
cmp al,0OOH 

je compare 
cmp files,O 

je all__done 


convert files, ten,message 
display message 
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see Function 1AH 
see Function 11H 
‘directory entry found? 
no, no files on disk 
;see end of chapter 
snext several lines 
;check date in directory 
‘entry against date 


' tabove & check next file 


if date in directory 
;entry isn’t earlier. 
‘THIS FUNCTION 
;bump deleted-files 
‘counter 

see Function 12H 
‘directory entry found? 
‘yes, check date 

sany files deleted? 
sno, display NO FILES 
*message. 

;see end of chapter 
;see Function 09H 
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Sequential Read (Function 14H) ran 


Call 

AH = 14H 

DS:DX 
Opened FCB 


O = Read completed successfully 
1 = EOF 

2 = DTAtoo small 

3 = EOF, partial record 


The record pointed to by the current block (offset OCH) and Current Record 
(offset 20H) fields is loaded at the Disk Transfer Address, then the Current Block 
and Current Record fields are incremented. 


ee ee eee AQ 
AL returns a code that describes the processing: 
Code Meaning 
QO Read completed successfully. 
1 End-of-file, no data in the record. 
2 Noenough room atthe Disk Transfer Address 
to read one record; read cancelled. 
3 End-of-file; a partial record was read and 


padded to the record length with zeros. 


Macro Definition: read__seq macro fcb 


mov dx,offset fcb 
mov ah,14H 

int 21H 

endm 
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Example 
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cas 
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The following program displays the file name TEXTFILE.ASC that is on the disk in 
drive B::; its function is similar to the Advance DOS TYPE command. If a partial 
record is in the buffer at end of file, the routine that displays the partial record 
displays characters until it encounters an end-of-file mark (ASCII 26, or 


CONTROL-2Z): 


fob db 2,°TEXTFILEASC”’ 


db 25 dup(?) 


ionVher 890 db =: 128 dup (?),"“$” 


func_.14H: set __dta buffer 
openfcb 

read_line: read__seqfc> 
cmp al,O2H 
je all__done 
cmp al,02H 


jg check__more 
display buffer 
jmp  read__line 
check_more:cmp al,03H 
jne_all__done 
xor Si, Si 
find_oef: cmp buffer{si],26 
je all__done 
display__char buffer[si] 
inc Si 


i jmp _ find__eof 
all__done: close fcb 


‘see Function 1AH 


‘see Function OFH 
‘THIS FUNCTION 
‘end-oft-file? 

‘yes 

;end-of-file with partial 
‘record? 

yes 
‘see Function 09H 

;get another record 
‘partial record in buffer? 
;no, go home 

‘set index to 0 

‘is character EOF? 
‘yes, no more to display 
‘see Function 02H 
sbump index to next 
‘character 

‘check next character 
‘see Function 10H 
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AX: Call 
BX: AH = 15H 
Cx: DS:DX 
Dx: Opened FCB 
Return 
AL 
OOH = Write completed successfully 
01H = Disk full 


O2H = DTA too small 


wee wee ee 


DX must contain the offset (from the segment address in DS) of an opened FCB. 
The record pointed to by Current Block (offset OCH) and Current Record (offset 
20H) fields is written from the Disk Transfer Address, then the current block and 
current record fields are incremented. 


The record size is set to the value at offset OEH in the FCB. If the Record Size is 
less than a sector, the data at the Disk Transfer Address is written to a buffer; the 
buffer is written to disk when it contains a full sector of data, or the file ts closed, or 
a Reset Disk system call (Function ODH) is issued. 


AL returns a code that describes the processing: 
Code Meaning 
QO Transfer completed successfully. 
1 Disk full; write cancelled. 
2 Not enough room at the Disk Transfer Address 
to write one record; write cancelled 


Macro Definition: write _.seq macro fcb 
mov dx,offset fcb 
mov ah,15H 
int 21H 
endm 
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Example 


The following program creates a file named DIR.TMP on the disk in drive B: that 
contains the disk number (0 = A;, 1 = B;, etc.) and filename from each directory 
entry on the disk: 


record_size equ) 14 ‘Offset of Record Size 
‘field in FCB 
fcb1 db 2,“DIR TMP” 
db 25 dup (7) 
feb2 db NALA a de a at ae ae ae a sl ' 
db 25 dup (7) 
buffer db 128 dup (7?) 
func__15H: set _dta buffer ‘see Function 1AH 
search__first feb2 ‘see Function 11H 
cmp al,FFH | ‘directory entry found? 
je all__done ‘no, no files on disk 
create feb1 ‘see Function 16H 
mov fcb1{record__size]},12 
‘set record size to 12 
write__it: write__seq  fcb1 ‘THIS FUNCTION 
search__nextfcb2 ‘see Function 12H 
cmp al,-FFH ‘directory entry found? 
je all_done :no, go home 
jmp write__it ‘yes, write the record 


all_done: close fcb1 ‘see Function 10H 


se eee 


_ . ( ee 
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Create File (Function 16H) 


DX must contain the offset (from the segment address in DS) of an unopened 
FCB. The directory is searched for an empty entry or an existing entry for the 
specified filename. 


— 


pI 
Call 
AH = 16H 
DS:DX 
Unopened FCB 


OOH = Empty directory found 
FFH (255) = No empty directory available © 


File system call (Function OFH) is called, and AL retums 0. You can create a 


lf an empty directory entry is found, it is initialized to a zero-length file, the Open Ks J Q 


a. 


ere oe ee eee OO eee 


hidden file by using an extended FCB with the attribute byte (offset FCB-1) set to 


ee me ee eee eee = Secememees = ae 


lf an entry is found for the specified filename, all data in the file is released, making 
a zero-length file, and the Open File system call (Function OFH) is issued for the 
filename (in other words, if you try to create a file that already exists, the existing 
file is erased, and a new, empty file is created). 


lf an empty directory entry is 


not found and there is no entry for the specified 


filename, AL retums FFH (255). 


Macro Definition: create macro fcb 


mov 
mov 
int 
endm 


dx, offset fcb 
ah,16H 
21H 
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Example 


The following program creates a file named DIR. TMP on the disk in drive B: that 
contains the disk number (0 = A:, 1 = B:, etc.) and filename from each directory 


entry on the disk: 


record_size equ 14 ;Offset of Record Size 
‘field of FCB 

fcb1 db 2,"‘DIR TMP” 
db 25dup(?) 

fcb2 CD 2,°°077 7777777" 
db 25dup(?) 

buffer db 128 dup (7) 

func_.16H: setdta buffer ‘see Function 1AH 
search__first fcb2 ‘see Function 11H 
cmp al,FFH ‘directory entry found? 
je all__done ‘no, no files on disk 
create fcb1 ‘THIS FUNCTION 
mov fcb1{record__size]},12 

‘set record size to 12 

write__it: write__seq fcb1 -see Function 15H 
search_next fcb2 see Function 12H 
cmp al,FFH ‘directory entry found? 
je all_done no, go home 
jmp write__it ‘yes, write the record 

all_done: close feb1 see Function 10H 
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Rename File (Function 17) 


Call 

AH = 17H 

DS:DX 
Modified FCB 


Return 

AL 
OOH = Directory entry found 
FFH (255) = No directory entry 
found or destination already 
exists 


DX must contain the offset (from the segment address in DS) of an FCB with the 
drive number and filename filled in, followed by a second filename at offset 11H. 
The disk directory is searched for an entry that matches the first filename, which 
can contain the ? wild card character. 


lf a matching directory entry is found, the filename in the directory entry is 
changed to match the second filename in the modified FCB (the two filenames 
cannot be the same name). If the ? wild card character is used in the second 
filename, the corresponding characters in the filename of the directory entry are 
not changed. AL returns 0. 


lf a matching directory entry is not found or an entry is found for the second 
filename, AL returns FFH (255). 


Macro Definition: rename macro fcb,snewname 
mov dx,offset fcb 
mov ah,17H 
int 21H 
endm 


j Aas 
ZS 
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Example 


The following program prompts for the name of a file and a new name, then 
renames the file: 


fcb db 37 dup(?) 
prompt db “Filename: $”’ 
prompt2 db ‘Newname: 3” 


reply db 17 dup(?) 

crif db  13,10,"S”’ 
func__17H: display prompti — ‘see Function 09H 
get_string 15,reply -see Function OAH 
display crif ‘see Function 09H 
parse reply(2],fcb ‘see Function 29H 
display prompt2 ‘see Function 09H 
get_string 15,reply ‘see Function OAH 
| display crif ‘see Function 09H 

| parse reply(2],fcb[16] 

‘see Function 29H 
rename fcb ‘THIS FUNCTION 


tn oF wee oe 


eo Oe ee ee, > ee eee 
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Current Disk (Function 19H) 
Call 


BX: AH = 19H 
ox: [DHT OE 


AL 
Currently selected drive 
(O=A,1=8, etc.) 


AL returns the currently selected drive (O=A:,1=B:, etc.). 


Macro Definition: Current_disk macro 
Mov ah,19H 
int 21H 
endm 


Example 


The following program displays the Currently selected (default) drive in a 2-drive 
system: 


message db “Current disk is $” see Function OSH 
‘for explanation of $ 


crif db 13,10,"‘$" 

func__19H: display message See Function 09H 

| current__disk ; THIS FUNCTION 
cmp al,OOH Is it disk A? ° 
jne disk__b NO, it’s disk B: 
display__char “A” see Function 02H 
jmp all__done 

disk__b: display__char “‘B” See Function 02H 

all__done: display rif ‘see Function OSH 
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Set Disk Transfer Address (Function 1AH) 


Call 
AH = 1AH 
DS:DX 
Disk Transfer Address 


Return 
AL 


DX must contain the offset (from the segment address in DS) of the Disk Transfer 
Address. Disk transfers cannot wrap around from the end of the segment to the 
beginning, nor can they overflow into another segment. 


NOTE 


If you do not set the Disk Transfer Address, 
Advance DOS defaults to offset 80H in the 
- Program Segment Prefix. 


Macro Definition: set.dta macro buffer 
mov  dx,offset buffer 


mov  ah,1AH 
int 21H 
endm 


Example 


The following program prompts for a letter, converts the letter to its alphabetic 
sequence A = 1, B = 2, etc.), then reads and displays the corresponding record 
from a file named ALPHABET.DAT on the disk in drive B:. The file contains 
26 records; each record is 28 bytes long: 


record__size equ 14 Offset of Record Size 
‘field of FCB 
relative__record equ 33 offset of Relative Record 


‘field of FCB 


( BAY 
LE 


—_—_— 
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+E 
feb db 2,“ALPHABETDAT”’ 
db 25 dup(?) 
buffer db 34 dup,"$”" 
prompt db “Enter letter: $” 
crif db 13,10,°S" 
° yt 
func__1AH: setdta buffer Pa ‘THIS FUNCTION 
open fcb ‘see Function OFH 
mov feb(record__size],28 ;setrecord size 
get_char: display prompts ‘see Function 09H 
read__kbd__and__echo ‘see Function 01H 
cmp al,ODH just a CR? 
je all_done “yes, go home 
sub al,41H 245 sconvert ASCII 
a ‘code to record 7 _ 
mov fcb(relative__record],al 
‘set relative record 
display crif ‘see Function 09H 
read_ran feb ‘see Function 21H 
display buffer ‘see Function 09H 
display crif ‘see Function OSH 
imp get_char ‘get another character 


all_done: close fcb ‘see Function 10H 
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Random Read (Function 21H) 


Call 

AH = 21H 

DS:DX 
Opened FCB 


OOH = Read completed successfully 
01H = EOF 

02H = DTA too small 

03H = EOF, partial record 


— owe ewes + +e somm & o- -_ 


DX must contain the offset (from the segment address in DS) of an opened FCB. 


-The Current Block (offset OCH) and Current Record (offset 20H) fields are set to 
agree with the Relative Record field (offset 21H), then the record addressed by 
these fields is loaded at the Disk Transfer Address. 


AL returns a code that describes the processing: 
Code Meaning 
0 Read completed successfully. 


1 End-of-file; no data in the record. 


2 Not enough room at the Disk Transfer Address to read one record: 
read cancelled. 


3. End-of-file; a partial record was read and padded to the record length 
with Zeros. 


Macro Definition: read__ macro feb 
mov  dx,offset fcb 
mov  ah,21H 
int 21H 
endm 


Qa ener Te eee eee - 
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Example 


The following program prompts for a letter, converts the letter to its alphabetic 
sequence (A = 1, B = 2, etc.), then reads and displays the corresponding record 
from a file named ALPHABET.DAT on the disk in drive B:. The file contains 
26 records; each record is 28 bytes long: 


record__size equ 14 ‘offset of Record Size 
‘field of FCB 
relative__record equ 33 ‘offset of Relative Record 
| ‘field of FCB 
feb db 2,“ ALPHABETDAT” 
db 25dup(?) 
buffer db 34 dup(7?),‘‘S’’ 
prompt db “Enter letter: $” 
crif db 13,10,"S” 
func__21H: set_dta buffer ‘see Function 1AH 
open fcb ‘see Function OFH 
mov feb (record__size],28 ;setrecord size 
get__char: display prompt ‘see Function 09H 
read__kbd__and echo ‘see Function 01H 
cmp al,ODH ‘just a CR? 
je all_done ‘yes, go home 
sub al,41H ‘convert ASCII code 
‘to record # 
mov fcb[relative__record],al ;set relative 
record 
display crif ‘see Function 09H 
read_ran fcb ‘THIS FUNCTION 
display buffer ‘see Function 09H 
jmp get__char get another char. 


all__done: close fcb ‘see Function 10H 


aol > 
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Call 

AH = 22H 
DS:DX 
Opened FCB 


OOH = Write completed successfully 
01H = Disk full 
02H = DTA too small 


DX must contain the offset (from the segment address in DS) of an opened FCB. 


The Current Block (offset OCH) and Current Record (offset 20H) fields are set to 
agree with the Relative Record field (offset 21H), then the record addressed by 
these fields is written from the Disk Transfer Address. If the record size is smaller 
than a sector (512 bytes), the records are buffered until a sector is ready to write. 


AL returns a code that describes the processing: 
Code Meaning 
0 Write completed successfully. 


1 Disk is full. 


2 Not enough room at the Disk Transfer Address to write one record; 
write cancelled. 
Macro Definition: write_ran macro fcb 
| mov  dx,offset fcb 


mov ah,22H 
int 21H 
endm 


Example 


The following program prompts for a letter, converts the letter to its alphabetic 
sequence (A = 1, B = 2, etc.), then reads and displays the corresponding record 
from a file named ALPHABET.DAT on the disk in drive B:. After displaying the 
record, it prompts the user to enter a changed record. If the user types a new 
record, it is written to the file; if the user just presses RETURN, the 


—— 
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record is not replaced. The file contains 26 records; each record is 28 bytes long: 
‘Offset of Record Size 


record__size equ 14 


relative_record equ 33 


fcb 


buffer 
prompt 
prompt2 
Crif 


reply 
blanks 


func__22H: 


get__char: 


all__done: 


db 2,“ALPHABETDAT” 
db . 25 dup (7?) 

db.” 26 dup(?),13,10,‘'$” 
db “Enter letter: $”’ 


‘field of FCB 


‘offset of Relative Record 


‘field of FCB 


db ‘‘Newrecord (RETURN for no change): $’’ 


db 13,10,"$” 
db 28 dup (32) 
db 26 dup (32) 


v 
set_dta buffer 
open feb of 
Mov fcb[record__size],32 


display promptt 
read__kbd__and__echo 


cmp al,0ODH 
je all__done 
sub al,41H 
mov fcb{relative__record],al 
display __crif 
read__ran feb 
display _ buffer 
Fdisplay rif 
Yisplay  prompt2 
get_-string 27,reply 
display —crif 
cmp reply(1],0 
je get__char 
xor bx, bx 


mov bl ,replty[1] 


move__string blanks, buffer, 26” ab 

move__string reply[2],buffer,bx 
|_write_ranfeb 

jmp get__char 

close feb 


‘see Function 1AH 
‘see Function OFH 
‘set record size 
‘see Function 09H 
‘see Function 01H 
‘just a CR? 

‘yes, go home 
‘convert ASCII 
‘code to record # 


-set relative record 
‘see Function 09H 
‘THIS FUNCTION 
‘see Function 09H 
‘see Function OSH 
‘see Function 09H 
‘see Function OAH 
‘see Function 09H 


;was anything typed 


sbesides CR? 

no 

‘get another char. 
‘to load a byte 


‘use reply length as 


‘counter 

‘see chapter end 
‘see chapter end 
‘THIS FUNCTION 


‘get another character 


‘see Function 10H 


j= 


: j 122 
Bove 
LN 
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File Size (Function 23H) 


Call 

AH = 23H 

DS:DX 
Unopened FCB 


OOH = Directory entry found 
FFH (255) = No directory entry found 


— 


| DX must contain the offset (from the segment address in DS) of an unopened 
FCB. You must set the Record Size field (offset OEH) to the proper value before 
Calling this function. The disk directory is searched for the first matching entry. 


Ifa matching directory entry is found, the Relative Record field (offset 21 H) is set 
to the number of records in the file, calculated from the total file size in the 
directory entry (offset 1CH) and the Record Size field of the FCB (offset OEH). AL 
returns 00. 


If no matching directory is found, AL returns FFH (255). 


NOTE 


If the value of the Record Size field of the FCB 
(offset OEH) doesn’t match the actual number of 
characters in a record, this function does not return 
the correct file size. If the default record size (128) 
is not correct, you must set the Record Size field to 
the correct value before using this function. 


= ee sw ee eee eness. 


: aN 
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Macro Definition: file__size macro feb 
mov dx,offset fcb 


mov ah,23H 
int 21H 
endm 


Example 


The following program prompts for the name of a file, opens the file to fill in the 
Record Size field of the FCB, issues a File Size system call, and displays the file 


size and number of records in hexadecimal: 


feb db 37 dup(?) 
promot db “Filename: $” 
msg1 db ‘‘Record length: 713.10, o a 
msg2 db “Records: "43,10, 3" OO 7 
crif ab 13,10,"5" 
reply db 17 dup(?) 
sixteen db 16 
func__23H: display prompt see Function 09H 
get__string 17,reply see Function OAH 
cmp __reply[1],0 Just a CR? 
jne get_length no, keep going 
jmp __all__done ‘yes, go home 
get_length: display crif see Function 09H 
parse reply(2},fcb see Function 29H 
open fcb see Function OFH 
file__size feb sTHIS FUNCTION 
mov si,33 ‘offset to Relative 
‘Record field 
mov di,9 | reply in msg__2 
convert_it: cmp _ febfsi],0 ‘digit to convert? 
je show__it NO, prepare message 
convertfcb/si],sixteen,msg__2{di] 
inc Si ‘bump n-o-r index 
inc di ;bump message index 
jmp —_convert__it ;Check for a digit 
show _it: convertfcb[14],sixteen,msg__1[15] | 
display msgq—1 ;see Function 09H 
display msg__2 see Function 09H 
jmp — func__23H ‘get a filename 


all_done: close feb ‘see Function 10H 


Rd 
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Set Relative Record (Function 24H) 


AX: Call 

Rx: AH = 24H 

Cx DS:DX 

Dx: Opened FCB 
Return 
None 


DX must contain the offset (from the segment address in DS) of an opened FCB. 
The Relative Record field (offset 21H) is set to the same file address as the 


Current block (offset OCH) and Current Record (offset 20H) fields. 


Macro Definition: set__relative__record macro fcb 
mov  dx,offsetfcb 


mov ah,24H 
int 21H 
endm 


Example 


The following program copies a file using theRandom Block Read and Random 
Block Write system calls. It speeds the copy by setting the record length equal to 
the file size and the record count to 1, and using a buffer of 32K bytes. It positions 
the file pointer by setting the Current Record field (offset 20H) to 1 and using Set 
Relative Record to make the Relative Record field (offset 21H) point to the same 
record as the combination of the Current Block — OCH) and Current Record 
(offset 20H) fields: 


current__record equ 32 ‘Offset of Current Record 
: ‘field of FCB 
file__size equ 16 ‘Offset of File Size 
| ‘field of FCB 
feb dd 37 dup(?) 
filename db 17 dup(7?) 
promptt db “File to copy: $’’ ‘see Function OSH for 
prompt2 db ‘Name of copy: $” ‘explanation of $ 


crif db 13,10,°$” 


[? 
BAS 
ae 


Chapter One 


file__length 
buffer 


func__24H: 
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dw ? 
db 32767 dup(?) 
set_dta buffer see Function 1AH 
display promptt see Function 09H 
get_string 15,filename see function OAH 
display —crif see Function 09H 
parse _ filename([2],fcb see Function 29H 
open fcb ‘see Funciton OFH 
mov fcb(current_record],0 ;set Current Record 
‘field 
set_relative__record fcb ‘THIS FUNCTION 
mov ax,word ptrfcb{file__size] ;get file size 
mov file__length,ax Save it for 
sran__block__write 
ran__block__read fcb,1,ax ;see Function 27H 
display prompt2 see Fnction 09H 
get_-string 15,filename see Function OAH 
display — crif see Function 09H 
parse _ filename{2],fcb see Function 29H 
create fcb ;see Function 16H 
mov feb([current_record],0 ;set Current Record 
field 
set__relative__record fcb ‘THIS FUNCTION 
mov ax, file__length ‘get original file 
‘length 
ran__block__write fcb,1,ax see Function 28H 


close fob ‘see Function 10H 
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WAY 
Set Vector (Function 25H) , 


AX: Call 
BX: AH = 25H 
AL 
x: 
: x: Interrupt number 
DS:DX 


Interrupt-handling routine 


Return 
None 


Function 25H should be used to set a particular interrupt vector. The operating 
system can then manage the interrupts on a pre-process basis. Note that 
programs should never set interrupt vectors by writing them directly in the low 
memory vector table. 


DX must contain the offset (from the segment address in DS) of an interrupt- 
handling routine. AL must contain the number of the interrupt handled by the 
routine. The address in the vector table for the specified interrupt is set to DS:DX. 


Macro Definition: 
set__vector macro interrupt,seg__addr,off__ddr 
mov _ al,interrupt 


push ds 
mov ax,seg__addr 
mov  ds,ax 
mov  dx,off__addr 
mov ah,25H 
int 21H 
pop ds 
endm 
Example 
Ids dx, intvector 
mov ah,25H 
mov al,intnumber 
int 21H 


‘There are no errors returned 
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Random Block Read (Function 27H) 


Call 

AH = 27H 

DS:DX 
Opened FCB 

CX 


Number of blocks to read 


Return 
or] 


OOH = Read completed successfully 


01H = EOF 
02H = End of segment 
FLAGS, ,| FLAGS, 03H = EOF, partial record 
CX 
Number of blocks read 


DX must contain the offset (from the segment address in DS) of an opened FCB. 
CX must contain the number of records to read; if it contains 0, the function 
returns without reading any records (no operation). The specified number of 
records -- calculated from the Record Size field (offset OEH) -- is read starting at 
the record specified by the Relative Record field (offset 21H). The records are 
placed at the Disk Transfer Address. 


AL returns a code that describes the processing: 
Code Meaning 
O Read completed successfully. 
1 End-of-file; no data in the record. 


2  Notenoughroom atthe Disk Transfer Address to read one record; read 
cancelled. 


3 End-of-file; a partial record was read and padded to the record length 
with zeros. 


CX returns the number of records read; the Current Block (offset OCH), Current 
Record (offset 20H), and Relative Record (offset 21H) fields are set to address 
the next record. 


Macro Definition: 
ran__block__read macro fcb,count,rec__size 
mov dx,offset fcb 
mov cx,count 
mov word ptr fcb[14],rec__size 
mov  ah,27H 
int 21H 
endm 


i? TE? BAY 
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Example 


The following program copies a file using the Random Block Read system call. It 
speeds the copy by specifying a record count of 1 and a record length equal to the 
file size, and using a buffer of 32K bytes; the file is read as a single record 
(compare to the sample program for Function 28H that specifies a record length 
of 1 and a record count equal to the file size): 


current_record equ 32 ‘offset of Current Record field 


file__size equ 16 ‘Offset of File Size field 
feb db 37 dup(?) 
filename db 17 dup(?) 
promptt db “File tocopy: $” see Function 09H for 
prompt2 db “Name of copy: $” ‘explanation of $ 
crif db 13,10,“$” 
file_length dw ? 
buffer db 932767 dup(?) 
func_.27H: set_dta buffer ‘see Function 1AH | 
display promptt ;see Function 09H : 
get_string 15,filename ‘see Function OAH 
display crif ‘see Function 09H 
parse filename[2],fcb see Function 29H 
open fcb ‘see Function OFH 
mov fcb(current__record],0 ;set Current 
‘Record field 
set__relative__record fcb ‘see Function 24H 
mov ax, word ptr fcb/[file__size] 
‘get file size 
mov file__length,ax ‘save it for 
: sran__block__write 
ran__block__read fcb,1,ax ‘THIS FUNCTION 
display prompt2 see Function OSH | 
* get_string 15,filename see Function OAH | 
display crif ‘see Function OSH 
parse filename([2],fcb ‘see Function 29H 
create fcb ‘see Function 16H | 
mov feb(current_record],0 : 
set Current Record | 
‘field : 
set__relative__record fcb ‘see Function 24H 
mov ax, file__length ;get original file 
‘size 
ran__block__write fcb,1,ax ‘see Function 28H 


close fob 


‘see Function 10H 


Chapter One Systems Calls Page 1-78 


Call 

AH = 28H 

DS:DX 
Opened FCB 

CX 


Number of blocks to write 
(0 = set File Size field) 


Returm 

AL 
OOH = Write completed successfully 
01H = Disk full 
O2H = End of segment 

CX 


Number of blocks written 


ee ee eee oe + ore 


DX must contain the offset (from the segment address in DS) of an opened FCB; 
CX must contain either the number of records to write or 0. The specified number 
of records (calculated from the Record Size field, offset OEH) is written from the 
Disk Transfer Address. The records are written to the file starting at the record 
specified inthe Relative Record field (offset 21H) of the FCB. if CX is 0, no records 
are written, but the File Size field of the directory entry (offset 1CH) is set to the 
number of records specified by the Relative Record field of the FCB (offset 21H); 
allocation units are allocated or released, as required. 


a ae + oe eee —— eee ome + ee 


AL returns a code that describes the processing: 
Code Meaning 
Q Write completed successfully. 
1. Disk full. No records written. 
2 Notenoughroomatthe Disk Transfer Address to read one record; read 
cancelled. 


CX returns the number of records written; the Current Block (offset OCH), Current 
Record (offset 20H), and Relative Record (offset 21H) fields are set to address 
the next record. 
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Macro Definition: / Se EER 


ran__block__write macro fcb,count,rec__size 


~ 
mov  dx,offset fcb UD 


mov  cx,count 
mov word ptr fcb[14],rec__size 


mov ah 28H 
int 21H 
endm 


Example 


The following program copies a file using the Random Block Read and Random 
Block Write system calls. It speeds the copy by specifying a record count equal to 
the file size and a record length of 1, and using a buffer of 32K bytes; the file is 
copied quickly with one disk access each to read and write (compare to the 


sample program of Function 27H, that specifies a record count of 1 and a record 
length equal to file size): : 


current_record equ 32 ‘offset of Current Record field 

file__size equ 16 ‘offset of File Size field 

fcb db 37 dup(?) 

filename db 17 dup(7?) 

promptt db ‘File to copy: $” ‘see Function O9H for 

prompt2 db “Name of copy: $” ;explanation of $ 

crif ab 13;10,°S" ) 

num_recs dw ? 

buffer db 32767 dup(?) 

func_28H: setdta buffer ‘see Function 1AH 
display prompt ‘see Function 09H 
get_-string 15, filename see Function OAH 
display crif ;see Function 09H 
parse filename[2],fcb ‘see Function 29H 
open feb ‘see Function OFH 
mov fcb{current__record],0 

‘see Current Record 
‘field 
set__relative__record fcb ‘see Function 24H - 
mov ax, word ptr fcb(file__size] 
‘get file size 

mov num__recs,ax ‘save it for 


‘ran__block__write 
ran__block_read fcb,num__recs,1 :THIS FUNCTION 


display prompt2 ‘see Function OSH 
get_string 15,filename ‘see Function OAH 
display crif ‘see Function 09H 
parse filename([2],fcb _ ‘see Function 29H 


create fcb ‘see Function 16H 


GO| 
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mov fcb(current_record],0 ‘set Current 
‘Record field 
set_relative__record fcb -see Function 24H 
mov ax. file__length -get size of original 


ran__block__write fob,num__recs,1 :see Function 28H 
close fcb ‘see Function 10H 


Chapter One 


Parse File Name (Function 29H) 


we <— ee ee ee eee + 
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Controls parsing (see text) 
DS:S! 
String to parse 


Unopened FCB 


OOH = No wild card characters 
01H = Wild-card characters used 
FFH = Drive letter invalid 

DS:SI 
First byte past string that was 
parsed 

ES:DI 
Unopened FCB 


SI must contain the eak (to the segment address in DS) of a string (command 
line) to parse; DI must contain the offset (to the segment address in ES) of an 
unopened FCB. The String is parsed for a filename of the form d:filename.ext; if 
__one is found, a corresponding unopened FCB i is created at ES: DI. 


awe 


Bits 0-3 of AL control the parsing and processing. Bits 4-7 are er 


Bit Value Meaning 


0 0 
1 0 
al 
0 
3 1 
0 


All parsing stops if a file separator is encountered. 

Leading separators are ignored. 

The drive number in the FCB is set to 0 (default drive) if the string 
does not contain a drive number. 

The drive number in the FCB is not changed if the string does not 
contain a drive number. 

The filename in the FCB is not changed if the string does not 
contain a filename. 

The filename in the FCB is set to 8 blanks if the in does not 
contain a filename. 

The extension in the FCB is not changed if the string does not 
contain an extension. 

The extension in the FCB is set to 3 blanks if the string does not 
contain an extension. 


If the filename or extension includes an asterisk (*), all remaining characters in 
the name or extension are set to question mark (7). 


LU L- 


} 
AS sie 


—cwepews WIIG WY VlCilliso Valls rage i-Ga +O > 


Filename separators: 


LAK 


-.t,=+/"[] <>  spacetab 


Filename terminators include all the filename separators plus any control 
character. A filename cannot contain a filename terminator; if one is encountered, 


parsing stops. 


lf the string contains a valid filename: 


1. AL returns 1 if the filename or extension contains a wild card 
character (* or 7); AL retums 0 if neither the filename nor extension 
contains a wild card character. 


2.  DS:DI point to the first character following the string that was 


parsed. 


- 


ES:DI point to the first byte of the unopened FCB. 


lf the drive letter is invalid, AL returns FFH (255). If the string does not contain a 
valid filename, ES:DI+1 points to a blank (ASCII 32). 


Macro Definition: parse macro string,fcb 


mov si,offset string 
mov di,offset fcb 
push es 
push ds 
pop es 
mov al,oFH ;bits0,1,2,30n 
mov ah,29H 
int 21H 
pop es 
endm 
Example 
The following program verifies the existence of the file named in reply to the 
prompt: 
feb db 37 dup (7?) 
prompt db ‘Filename: $”’ 
reply db 17 dup(?) 
yes qdS “FILE ExiStS",13,10,"S" 
no dd “FILE DOES NOT EXIST”, 13,10,'$” 
func_.29H: display prompt see Function 09H 
get_string 15,reply ‘see Function OAH 
parse reply([2],fcb ‘THIS FUNCTION 
search__first fcb | ‘see Function 11H 


° 
SN Se ee ~~ «= - 


~ Fe mee cam ae Ace wees 


Chapter One Systems Calls 
4 cert 
cmp al | FF 
iS not__there 
jmp continue 
not_there: display no 


continue: 
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‘dir. entry found? 
no 


a ee ——— as 
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Get Date (Function 2AH) 

AX: : Call 

BX: AH = 2AH 

CX: 

ae Return 
CX 


Year (1980 - 2099) 
DH 
Month ( 1 - 12) 
DL 
Day (1-31) 
AL 
Day of week (O=Sun., 6=Sat.) 


This function returns the current date set in the operating system as binary 
numbers in CX and Dx: 


CX Year (1980-2099) 

DH Month (1 = January, 2 = February, etc.) 

DL Day (1-31) 

AL Day of week (0 = Sunday, 1 = Monday, etc.) 


Macro Definition: get__date macro 
mov ah,2AH 
int 21H 
endm 


Example 


The following program gets the date, increments the day, increments the month 
or year, if necessary, and sets the new date: 


month db 31,28,31,30,31,30,31,31,30,31,30,31 

func_2AH: get_date see above 
inc di ‘increment day 
xor ‘ bx, bx ‘so BL can be used as index 
mov bi,dh ‘move month to index register 
dec bx ‘month table starts with 0 
cmp —_ di,month{bx] ‘past end of month? 
jle month__ok ‘no, set the new date 
mov di,1 ‘yes, set day to 1 
inc dh ‘and increment month 


cmp dh12 ‘past end of year? 


SSS OE + ee eee 
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jle month__ok sno, set the new date 
mov dh,1 ‘yes, set the month to 1 
inc CX 


‘increment year 


month__ok: set__date cx,dh,dl “THIS FUNCTION 


- ~NEW tamed wikia cs 
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Call 
AH = 2BH 
CX 
Year (1980 - 2099) 
DH 


Month (1 - 12) 
DL 


Day (1 - 31) 


Return 
AL 


OOH = Date WaS valid 


SP 
PRS a FFH (255) = Date WasS invalid 


Registers CX and DX must contains a valid date in binary: 


CX Year (1980-2099) 
DH Month t= January, 2 = February, etc.) 
DL Day (1-31) 


If the date is valid, the date is set and AL returns 0. If the date is Not valid, the 
function is Cancelled and AL returns FFH (265). 


Macro Definition: Set_date macro year,month, day 
MOV ex, year 


mov I,day 
MOV  ah,2BH 
int 21H 
endm 


Example 


The following Program gets the date. increments the day, increments the month 
Or year, if Necessary, and sets the new date: 


Month db 31,2831 130,31,30,31 :31,30,31 130,31 

func__2BH: get_date ‘S@6 Function 24H 
Inc d! ‘increment day 
XOr bx, bx ‘SO BL can be USEd as index 
Mov Bi,dh /MOve month to index register 
dec bx Month table starts with 0 
cmp dl, month [bx] ‘Past end of month? 
les month__ok NO, Set the new date 


“7 Samu ee. comme ~~ me ss ae 7 ememn. 2 Sse Ee os es MOMS ge sdk 
‘ 
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mov di,1 
inc dh 
cmp  dh,12 
jle month__ok 
mov dh,1 
inc cx 
month__ok: set__date cx,dh,dl 


’ 


/ WS | 
Page 1-8 | Z 
“yes, set day to 1 Web 
-and increment month 


‘past end of year? 

‘no, set the new date 
“yes, set the month to 1 
‘increment year 


‘THIS FUNCTION 


. 
« 
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! 


ad 
Get Time (Function 2CH) / Za 


BX: AH = 2CH 

GX: ‘2 

es Return UO { 
CH 


Hour (0 - 23) 
CL 
Minutes (0 - 59) 
H 
Seconds (0 - 59) 
DL 
Hundredths (0 - 99) 


This function returns the current time set in the operating system as binary 
numbers in CX and Dx: 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredcths of a second (0-99) 


Macro Definition: get__time macro 
mov ah,2CH 
int 21H 
endm 


a 


Example 


The following program continuously displays the time until any key is pressed: 


time db ‘‘00:00:00.00"’,13,10,‘‘$”’ 

ten db 10 

func_.2CH: get_time ‘THIS FUNCTION 
convert ch,ten,time ;see end of chapter 
convert cl,ten,time[3] see end of chapter 
convert dh,ten,time[6] ;see end af chapter 
convert dl,ten,time[9] see end of chapter 
display time ;see Function 09H 
check__kbd__status see Function OBH 
cmp al,FFH has a key been pressed? 
je all__done ‘yes, terminate 


jmp = func__2CH _ 3no, display time 


| , A a. 
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———— —F 
Set Time (Function 2DH) 
AX: Call 
BX: AH = 2DH 
COX: CH 
Hour (0 - 23) 
Dx: CL 


Minutes (0 - 59) 
H 


a: ae Seconds (0 - 59) 
DL 

a ae Hundredths (0 - 99) 

a a ee 


wn 
: 
O 


FLAGS, ,| FLAGS, AL 
OOH = Time was valid 

FFH (255) = Time was invalid 

=: ae 


FSS — _ | = = : AR —_ 


Registers CX and DX must contain a valid time in binary: 


CH Hour (0-23) 

CL Minutes (0-59) 

DH Seconds (0-59) 

DL Hundredths of a second (0-99) 


If the time is valid, the time is set and AL returns 0. If the time is not valid, the 
function is cancelled and AL returns FFH (255). 


Macro Definition: 
set_time macro hour,minutes,seconds,hundrecths 
mov ch,hour 
mov _ci,minutes 
mov dh,seconds 
mov di,hundredths 


mov  ah,2DH 
int 21H 
endm 

Example 


The following program sets the system clock to 0 and continuously displays the 
time. When a character is typed, the display freezes; when another character is 
typed, the clock is reset to 0 and the display starts again: 


time db  “00:00:00.00",13, 10"$” 
ten db 10 
ftunc__2DH: set_time 0,0,0.0 THIS FUNCTION 


read__clock: get_time ‘see Function 2CH 


Uf 
UD 


Chapter One 


stop: 


Systems Calls 


convert ch,ten,time 
convert cl,ten,time/[3] 
convert dh,ten,time[6] 
convert dl,ten,time(9] 


display time 
dir__console__io FFH 
cmp al,OOH 

jne stop 

jmp read__clock 
read__kbd 


jmp func__2DH 


see end of chapter 
see end of chapter 
see end of chapter 
See end of chapter 
see Function 09H 
see Function 06H 
WaS a Char. typed? 
yes, Stop the timer 
no keep timer on 
see Function 08H 
‘keep displaying time 


mae + 
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Set/Reset Verify Flag (Function 2EH) 


Call 

AH = 2EH 

AL 
OOH = Do not verify 
01H = Verify 


[P| Retum 
None 


AL must be either 1 (verify after each disk write) or 0 (write without verifying). 
Advance DOS checks this flag each time it writes to a disk. 


The flag is normally off; you may wish to tum it on when writing critical data to disk. 
Because disk errors are rare and verification slows writing, you will probably want 


to leave it off at other times. 


Macro Definition: verify macro switch 
mov al,switch 
mov ah,2EH 
int 21H 
endm 


Example 


The following program copies the contents of a single-sided disk in drive A: to the 
disk in drive B:, verifying each write. It uses a buffer of 32K bytes: 


on equ 1 
off ‘equ 0 


prompt db ‘Source in A, target in B’’,13,10 
db “Any key to start. $’’ 
0) 


Start dw 
' buffer db 64 dup (512 dup(?)) °64 sectors 
func__2DH: display prompt ‘see Function 09H 
read__kbd ‘see Function 08H 


verify on sTHIS FUNCTION 


id 


) eS 
| FS 


eaeomeae ses © oot 
owes wo en a ee ae 
eet ee 


a 


Wo, 
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mov cx,5 scopy 64 sectors 
‘5 times 
copy: push cx ‘save counter 


abs__disk__read 0O,buffer,64,start 

‘see Interrupt 25H 
abs__disk__write 1,buffer,64,start 

see Interrupt 26H 


add __start,64 ;do next 64 sectors 

pop cx restore counter 

loop copy ‘do it again 

verify off > THIS FUNCTION 
disk_read O,buffer,64,start ‘see Interrupt 25H 


abs__disk__write 1,buffer,64,start 
see Interrupt 26H 


add _start,64 ‘do next 64 sectors 
pop cx ‘restore counter 
loop copy ;do it again 


verify off 


ee Oe Oem wee 
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Get Disk Transfer Address (Function 2FH) 


Call 
AH = 2FH 
OX: 
DX: Return 
ES:BxX 4 


Points to Disk Transfer Address 


Error returns: 
None. 


Example 


mov ah,2FH 
int 21H 


Function 2FH returns the DMA transfer address. 
| 
| “es:bx has current DMA transfer address 
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Get DOS Version Number (Function 30H) 


Call 

AH = 30H 

Return 

AL 
ae Major version number 
| BP AH 
a ae Minor version number 

FLAGS, , |FLAGS, 

2: a 2 


This function returns the Advance DOS version number. On retum, AL.AH will be 
the two-part version designation; i.e., for Advance DOS 2.11, AL would be 2 and 
AH would be 11. 


Error returns: 
None. 


Example: 


mov ah,30H 

int 21H 
- al is the major version number 
- ah is the minor version number 


. oe en 


me 0c 6 eee = 


I Yr 
coe 
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Keep Process (Function 31H) 
AX: : Call 
Bx: AH = 31H 
CX: AL 
Exit code 
DX: Dx 


Memory size, in paragraphs 


Return 
None 


This call terminates the current process and attempts to set the initial allocation 
block to a specific size in paragraphs. It will not free up any other allocation blocks 
belonging to that process. The exit code passed in AX is retrievable by the parent 
via Function 4DH. 


This method is preferred over Interrupt 27H and has the advantage of allowing 
more than 64K to be kept. | 


Error returns: 
None. 


$ 


Example 


mov . al,exitcode 
mov dx,parasize 


Mov ah,31H 
int 21H 


| 


CONTROL-C Check (Function 33H) 


Function 
OOH = Request current state 
01H = Set state 
DL (if setting) 
OOH = Off 
01H =On 


Advance DOS ordinarily checks fora CONTROL-C on the controlling device only 
when doing function call operations 01H-OCH to that device. Function 33H allows 
the user to expand this checking to include any system call. For example, with the 
CONTROL-C trapping off, all disk I/O will proceed without interruption; with 
CONTROL-C trapping on, the CONTROL-C interrupt is given at the system call 
that initiates the disk operation. 


Programs that wish to use calls O6H or 07H to 
read CONTROL-Cs as data must ensure that the 


NOTE 


CONTROL-C check is off. 


The function passed in AL was not in the range 0:1. 


Error return: 

AL = FF 
Example 

mov di,val 

mov ah,33H 

mov al,func 

int 21H 


: If al was 0, then di has the current value 
‘of the CONTROL-C check 
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Get Disk Free Space (Function 36H) 


AX: Call 
BX: AH = 36H 
DL 
eh Drive (0 = Default 
1 =A, etc.) 
Return 
BX 
Available clusters 
DX 
Clusters per drive 
Bytes per sector 
AX 


FFFF if drive number is invalid: 
otherwise sectors per cluster 


This function returns free space on disk along with additional information about 
the disk. 


Error returns: 


AX = FFFF 
The drive number given in DL was invalid. 


Example 
mov ah,36H 
mov di,Drive ‘O = default, A = 1 


int ; bx = Number of free allocation units on drive 
; dx = Total number of allocation units on drive 
; CX = Bytes per sector 
; ax = Sectors per allocation unit 


por SETS REPLI TRAIL OO INT P 
eure wr 


a YW 
Ax, Ax Y Rear dee. 


XokR 
VW. oes Ane , Ee eae Ae 
—* 2) 


5a 


ZC ek thw ep anon clianec Wa Kunnadly 2 
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Retum Country-Dependent Information (Function 38H) 


Se a G os ben Bassey 9 Be cts a Call 
ex: [BH [et] AH =6h 
Cx: | CH [ CL} DS:Dx 


Pointer to 32-byte memory area 
AL 


Ss ile 


Pst Retum 
[I Caryset 
AX 


2 = file not found 
Carry not set: 
FLAGS, | FRAG), DX:DS filled in with country data 


The value passed in AL is either 0 (for current country) or a country code. Country 
Codes are typically the international! telephone prefix code for the country. 


If DX = —1, then the Call sets the current country (as returned by the AL=0 call) to 


the country code in AL. |f the country code is not found, the current country is not 
changed. 


NOTE 


Applications must assume 32 bytes of information. 
This means the buffer pointed to by DS:DX must 
be able to accommodate 32 bytes. 


Chapter One 


This function returns, in the block 


Information pertinent to intema 


Systems Calls 


tional applications: 


i ipecbinnciemee sc os 
IWORD Date/time format | 
liicniictiaemeg cee ee + 
| BYTE ASCIZ String | 
[Currency symbol | 
PAAR eran nnenirieneweseenenen “s 
[2 BYTE ASCIZ String | 
{thousands separator | 
| Sesniinisadese se ee + 
2 BYTE ASCIZ String | 
|decimal separator 

woe ee nnn — weee nee 
2 BYTE ASCIZ String | 
|date separator | 
Toate nnn enemnemensenennsnnene ce fe 
2 BYTE ASCIz string | 
|time separator | 
PF Aenea cneinmeueneneenee-.. + 
[1 BYTE Bit fieig | 
Te nrwtenen ne nemenennennnnene ne + 
[1 BYTE | 
|Currency places | 
+ -------.. weeeee anne ee wont 
[1 BYTE | 
[time format | 

pitta + 
IDWORD 
|Case Mapping call | 
TF eenwnennnee nk sabia eo 
[2 BYTE ASCIZ String | 
|data list separator | 
a eo 


The format of most of these ent 
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/~ &2. 
of memory pointed to by DS:DxX, the following Lz, 


= 
2 


ries is ASCIZ (a NUL terminated ASC] String), but 
a fixed size is allocated for each field for @asy indexing into the table. 


The date/time format has the following values: 


O— USA standard h 
1 — Europe standard h 
¢ — Japan standard 


‘m:s m/d/y 
‘m:S d/m/y 


y/m/d h:m:s 


Yaa > 
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The bit field contains 8 bit values. Any bit not currently defined must be assumed 
to have a random value. 


Bit O = 0 If currency symbol precedes the 
Currency amount. 
= | If currency symbol comes after 
the currency amount. 
Bit 1 = 0 If the currency symbol immediately 
precedes the currency amount. 
= | If there is a space between the 
currency symbol and the amount. 


The time format has the following values: 


0 - 12 hour time 
1 - 24 hour time 


The currency places field indicates the number of places which appear after the 
decimal point on currency amounts. 


The Case Mapping cail is a FAR procedure which will perform country specific 
lower-to-uppercase mapping on character values from 80H to FFH. It is called 
with the character to be mapped in AL. It returns the correct upper case code for 
that character, if any, in AL. AL and the FLAGS are the only registers altered. It is 
allowable to pass this routine codes below 80H; however nothing is done to 
characters in this range. In the case where there is no mapping, AL is not altered. 

Error returns: 

AX 

2 = file not found 
The country passed in AL was not found (no table for specified 


country). 
Example ~ 
Ids dx, bik 
mov ah, 38H 
mov al, Country__code 
int 21H 


-AX = Country code of country returned 


——. a oo ee eee ew * 


| 
! 
' 


ee eee eases it 
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Create Sub-Directory (Function 39H) Uy) > 


Call 
AH = 39H 
DX:DS 
Pointer to pathname 


Return 
Carry set: 
AX 
3 = path not found 
5 = access denied 
Carry not set: 
No error 


Given a pointer to an ASCIZ name, this function creates a new directory entry at 
the end. 


Error returns: 
AX 


3 = path not found 
The path specified was invalid or not found. 
5S = access denied | 
The directory could not be created (no room in parent directory), 
the directory/file already existed or a device name was specified. 


Example 
Ids dx, name 
mov ah, 39H 


int . 21H 


a 
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Remove a Directory Entry (Function 3AH) 


Call 
AH = 3AH 
DS:DX 


Pointer to pathname 


Return 
Carry set: 
AX 


3 = path not found 

S = access denied 

16 = current directory 
Carry not set: 

No error 
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Function 3AH is given as ASCIZ name of a directory. That directory is removed 


from its parent directory. 


Error returns: 
AX 
3 = path not found 
_ The path specified was invalid or not found. 
5S = access denied 


The path specified was not empty, not a directory, the root 


directory, or contained invalid information. 
16 = current directory 


The path specified was the current directory on a drive. 


Example 


lds dx. name 
mov ah, 3AH 
int 21H 
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Change the Current Directory (Function 3BH) 


Call 
AH = 3BH 
DS:DX 
Pointer to pathname 


Retum 

Carry set: 

AX 
3 = path not found 
No error 


oe to wee coe ee 


. —— 


Function 3BH is given the ASCIZ name of the directory which is to become the 
current directory. If any member of the specified pathname does not exist, then 
the current directory is unchanged. Otherwise, the current directory is set to the 
string. : 


Error returns: 
AX 
3 = path not found _ 
The path specified in DS:DX either indicated a file or the path was 
invalid. 


Example 


ids dx, name 
mov = ah, 3BH 
int 21H 


meee ee eee @ oe ee 
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Create a File (Function 3CH) 


Call 
AH = 3CH 
DS:DX 
Pointer to pathname 


File attribute 


Return 
Carry set: 
AX 


5 = access denied 

3 = path not found 

4 = too many open files 
Carry not set: 

AX is handle number 


Function 3CH creates a new file or truncates an old file to zero length in preparation 
for writing. If the file did not exist, then the file is created in the appropriate 
directory and the file is given the attribute found in CX. The file handle returned 
has been opened for read/write access. 


Error retums: 
AX 
5 = access denied 
The attributes specified in CX contained one that could not be 
created (directory, volume !D), a file already existed with a more 
inclusive set of attributes, or a directory existed with the same 
name. 
3 = path not found 
. The path specified was invalid. 
4 = too many open files 
_ The file was created with the specified attributes, but there were 
no free handles available for the process, or the internal system 
tables were full. 


Example 
Ids dx, name 
mov ah, 3CH 
mov cx, attribute 
int 21H 


- ax now has the handle 


aie 
CE 


u- Db 


Uys ate (PF uUleLUUIToOUn) 


Access 
0 = File opened for reading 
1 = File opened for wniting 


2 = File opened for both 
reading and writing uD | 


Return 

Carry set: 

AX 
12 = invalid access 
2 = file not found 


Co 5 = access denied 
DS 4 = too many open files 
SS Carry not set: 


AX is handle number 


Function 3DH associates a 16-bit file handle with a file. 


The following values are allowed: 
ACCESS Function 


0 file is opened for reading 
1 file is opened for writing 
2 file is opened for both reading and writing. 


DS:DX point to an ASCIZ name of the file to be opened. 


The read/write pointer is set at the first byte of the file and the record size of the file is 
1 byte. The retumed file handle must be used for subsequent I/O to the file. 


Error retums: 
AX 
12 = invalid access 
The access specified in AL was not in the range 0:2. 
2 = file not found 
The path specified was invalid or not found. 
5 = access denied 
The user attempted to open a directory or volume-id, or open a 
read-only file for wnting. 
4 = too many open files 
There were no free handles available in the current process or the 
internal system tables were full. 


eee 
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Example 

Ids dx, name 

mov  ah,3DH 

mov. al, access 

int 21H 


, ax has error or file handle 
, If successful open 


/ Vine 
42> 
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File handle 


Return 
Carry set: 
AX 


6 = invalid handle 
Carry not set: 
No error 


In BX is passed a file handle (like that retumed by Functions 3DH, 3CH or 45H), 
Function 3EH closes the associated file. Internal buffers are flushed. 
Error return: 
AX 
6 = invalid handle 


The handle passed in Bx was not currently open. 


Example 


Mov bx, handle 
mov ah, 3EH 
int 21H 


(thr, 
430 


Chapter One Systems Calls Page 1-109 


Read From File/Device (Function 3FH) 


Call 
AH = 3FH 
DS:DX 

Pointer to buffer 
CX 

Bytes to read 
BX 

File handle 


Retum 
Carry set: 
AX 


ee -— wee - ms te 


Number of bytes read 
6 = invalid handle 
5 = error set: 
Carry not set: 
AX = number of bytes read 


| a ~ -_—_ 


e+ eee 


Function 3FH transfers count bytes from a file into a buffer location. It is not 
guaranteed that all count bytes will be read; for example, reading from the 
keyboard will read at most one line of text. If the returned value is zero, then the 
program has tried to read from the end of file. 


All 1/O is done using normalized pointers; no segment wraparound will occur. 


Error returns: 


— = rete ee a fe Rt 


6 = invalid handle 
| The handle passed in BX was not currently open. 
5 = access denied 
The handle passed in BX was opened in a mode that did not allow 
reading. 


Example 


Ids dx, buf 
mov cx, count 
mov _ bx, handle 
mov  ah,3FH 
int 21H 
‘ax has number of bytes read 


! ous nen ee ee ee ee rw es te et 
RS ED EEE EES EEE EE 


Write to a File or Device (Function 40H) 


Call oe: 

Bie / Lg 

DS:DX OAT 
Pointer to buffer 


ox L322: 
Bytes to write a> 


BX 


File handle U4 | 


Retum 
Carry set: 
AX 
Number of bytes written 
6 = invalid handle 
5 = access denied 
Carry not set: 
AX = number of bytes written 


Function 40H transfers count bytes from a buffer into a file. It should be regarded 
as an error if the number of bytes written is not the same as the number 
requested. 


The write system call with a count of zero (CX = Q) will set the file size to the 
current position. Allocation units are allocated or released as required. 


All |/O ts done using normalized pointers; no segment wraparound will occur. 


Error returns: 
AX 
6 = invalid handle 
The handle passed in BX was not currently open. 
5 = access denied 
The handle was not opened in a mode that allowed writing. 


Example 


Ids dx, buf 
mov cx, count 
mov bx, handle 
mov  ah,40H 
int 21H 
, ax has number of bytes written 
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Delete a Directory Entry (Function 41H) - 


. 
Call fuay 
AH = 41H yr 
DS:DX pe % 
Pointer to pathname (t* L 


Retum 
Carry Set: 
AX 


2 = file not found 

5 = access denied 
Carry not set: 

No error 


Function 4 1H removesa directory entry associated with a filename. 


Error retums: 
AX 
2 = file not found 
The path specified was invalid or not found. 
5 = access denied 
The path specified was a directory or read-only. 


Example 


Ids dx, name 
mov  ah,41H 
int 21H 


{ 


b 
| 


=. 


- oe ne ee eens ee TD See 
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, meio 
Move File Pointer (Function 42H) 


Call 
AH = 42H 
CAD XxX 


Distance to move, in bytes 
AL 


Method of moving: 
(see text) 
BX 


File handle 
Retum 
Carry set: 
AX 


6 = invalid handle 
1 = invalid function 


Carry not set: 
. DX:AX = new pointer location 


oes 6 ar Se eee ee eee 


Function 42H moves the read/write pointer according to one of the following 
methods: 


Method Function 
O The pointer is moved to offset bytes from the beginning of the file. 
- 1 The pointer is moved to the current location plus offset. 
2 The pointer is moved to the end of file plus offset. 


Offset should be regarded as a 32-bit integer with CX occupying the most 
significant 16 bits. 


Error retums: 
AX Py 
6 = invalid handle 


The handle passed in BX was not currently open. 
1 = invalid function 


The function passed in AL was not in the range 0:2. 
Example 


mov  dx,offsetlow 
mov cx,offsethigh 
mov al, method 
mov bx, handle 
mov ah, 42H 
int ein 
- dx:ax has the new location of the pointer 


Una, wl Gi 


_—_— oo 
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Call 
AH = 43H 
DS:DX 
Pointer to pathname 
CX (if AL = 01) 
Attribute to be set 
AL 
Function 
01 Set to CX 
OO Return in CX 


Return 
Carry set: 
AX 


3 = path not found 

5 = access denied 

1 = invalid function 
Carry not set: 


CX attributes (if AL = 00) 
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Given an ASCIZ name, Function 42H will set/get the attributes of the file to those 


given in CX. 


AL Function 


QO  Retum the attributes of the file in CX. 
1 Set the attributes of the file to those in CX. 


Error returns: 
AX 


3 = path not found 


The path specified was invalid. 


5 = access denied 


The attributes specified in CX contained one that could not be 
changed (directory, volume ID). 


1 = invalid function 
The function passed in AL was not in the range 0:1. 


Example 
Ids dx,name 


mov cx, attribute 


mov al, func 
int ah, 43H 
int 21H 
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1/O Control for Devices (Function 44H) 


ee Call 
BX: AH = 44H 
; BX 
mh Handle 
BL 
Drive (for calls AL = 4,5 
O = default, 1 =A, etc.) 
DS:DX 
Data or buffer 
CX 
Bytes to read or write 
AL 


Function code; see text 


Return 

Carry set: 

AX 

6 = invalid handle 

1 = invalid function 
13 = invalid data 

5 = access denied 


Carry not set: 
AL = 2,3,4,5 
AX = Count transferred 
AL = 6,7 
00 = Not ready 
FF = Ready 


ye 
Pagel-114 f° Aa, , 
7 Caals 


, 


Ee 
Lbs 


| 


Function 44H sets or gets device information associated with an open handle, or 


sends/receives a control string to a device handle or device. 


The following values are allowed for function: 


Request Function 


O Get device information (returned in DX) 
Set device information (as determined by DX) 


Read CX number of bytes into DS:DX from device control channel. 
Write CX number of bytes into DS:DX from device control channel. 


same as 3 only drive number in BL O=default,A:=1,B:=2.... 


Get input status 


, 
c 
3 
4 Same as 2 only drive number in BL 0=default,A:=1,B:=2.... 
5 
6 
q 


Get output status 


This function can be used to get information about device channels. Calls can be 
made on regular files, but only calls 0,6 and 7 are defined in that case (AL=0,6,7). 


All other calls return an invalid function error. 
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Calls AL=0 and AL=1 
The bits of DX are defined as follows for calls AL=0 and AL=1. Note that the 


upper byte MUST be zero on a set call. 


15 14 131211109 8 6 6 4 1 
(e I iEIRIS | 
T : S|O;IAIP S 
R Reserved DIF IWIE C 
a fe C O 

V L T 


ISDEV = 1 if this channel is a device 
= 0 of this channel is a disk file (Bits 8-15 = 0 in this case) 


lf ISDEV = 1 
EOF = 0 if End Of File on input 
RAW +#é£==1 if this device is in Raw mode 

= Q if this device is cooked 
ISCLK = 1 if this device is the clock device 
ISNUL = 1 if this device is the null device 
ISCOT = 1 if this device is the console output 


ISCIN = 1 if this device is the console input 

SPECL = 1 if this device is special 

CTRL = Oif this device can not do control 
strings via calls AL=2 and AL=3. 

CTRL = 1/if this device can process 


control strings via calls AL=2 and AL=3. 
NOTE that this bit cannot be set. 
If ISDEV =0 


EOF = 0 if channel has been written 
Bits 0-5 are the block device number for the channel 


; (0=A:, 1 =B:, ...) 
_ Bits 15,8-13,4 are reserved and should not be altered. 
Calls 2..5: 


These four calls allow arbitrary control strings to be sent or 
received from a device. The call syntax is the same as the read 
and write calls, except for 4 and 5, which take a drive number in 


BL instead of a handle in BX. 
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An invalid function error is retumed if the CTRL bit (see above) is 0. 
An access denied is returned by calls AL=4,5 if the drive number is invalid. 


Calls 6,7: 
These two calls allow the user to check if a file handle is ready for input or 
output. Status of handles open to a device is the intended use of these Calls, 
but status of a handle open to a disk file is allowed, and is defined as follows: 


Input: 
Always ready (AL=FF) until EOF reached, then always not ready 
(AL=0) unless current position changed via LSEEK. 

Output: 
Always ready (even if disk full). 


NOTE 


The status is defined at the time the system is 
CALLED. On future versions, by the time control 
is retumed to the user from the system, the status 
retumed may NOT correctly reflect the true current 
State of the device or file. 


Error retums: 
AX 
6 = invalid handle 
The handle passed in BX was not currently open. 
1 = invalid function 


The function passed in AL was not in the range 0:7. 
13 = invalid data 


3 = access denied (calls AL=4..7) 


Chapter One 
Example 
mov bx, Handle 
(Ormov bl, drive 
mov dx, Data 
(orlds dx, buf 
mov cx, count 
mov ah, 44H 
mov al, func 
int 21H 


; For calls AL=2,3,4,5 AX is the number of bytes 


Systems Calls 


for calls AL=4,5 
O=deéfault,A:=1...) 


and 
for calls AL=2,3,4,5) 


; transferred (same as READ and WRITE). 


; For calls AL=6,7 AL is status retumed, AL=0 if 


; Status is not ready, AL=OFFH otherwise. 
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Duplicate a File Handle (Function 45H) 


Call 
AH = 45H 
BX 

File handle 
Retum 
Carry set: 
AX 


6 = invalid handle 

5 = too many open files 
Carry not set: 
AX = new file handle 


Function 45H takes an already opened file handle and retums a new handle that 
refers to the same file at the same position. 


Error retums: 

AX 

6 = invalid handle 
The handle passed in BX was not currently open. 

4 = too many open files 
There were no free handles available in the current process or the 
internal system tables were full. 


Example 


mov _bx, fh 
Mov ah, 45H 
int 21H 
; ax has the returned handle 
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Force a Duplicate of a Handle (Function 46H) 


Call 
AH = 46H 
BX 
Existing file handle 
CX 


New file handle 


Retum 
Carry set: 
AX 
6 = invalid handle 
4 = too many open files 
Carry not set: 
No error 


Function 46H takes an already opened file handle and returns a new handle that 
_refers to the same file at the same position. If there was already a file open on 
handle Cx, it is closed first. 


Error retums: 
AX — 
6 = invalid handle 
_ The handle passed in BX was not currently open. 
4 = too many open files : 
There were no free handles available in the current process or the 
internal system tables were full. 


Example 


mov bx, fh 
mov cx, newfh 
mov ah, 46H 
int 21H 


ame oe 
a 
RE ead 
oe =. ae 
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Return Text of Current Directory (Function 47H) 


DSPr DSS” 
Pointer to 64-byte memory area 


Drive number 


Return 
Carry set: 
AX 
15 = invalid drive 
Carry not set: 
No error 


Function 47H retums the current directory for a particular drive. The directory is 
root-relative and does not contain the drive specifier or leading path separator. 
The drive code passed in DL is O=default, 1=A:, 2=B:, etc. 


Error retums: 
AX 


15 = invalid drive 
The drive specified in DL was invalid. 


Example 
mov ah, 47H 
Ids Si,area 
mov di,drive 
int 21H 


; ds:si is a pointer to 64 byte area that 
; contains drive current directory. 


SSIES OTA OD ei SEE es © Gertie em ee ee 


ee ee 
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Allocate Memory (Function 48H) 


Function 48H returms a pointer to a free block of memory that has the requested 


size in paragr 


aphs. 


Error returms: 
AX 


8 = not enough memory 


7 = arena trashed 


Example 


mov 
mov 
int 


Call 
AH = 48H 
BX 
Size of memory to be allocated 


Retum 


Carry set: 
AX 
8 = not enough memory 
7 = arena trashed 
BX 
Maximum size that could be allocated 
Carry not set: 
AX:0 
Pointer to the allocated memory 


The largest available free block is smaller than that requested or 
there is no free block. 


The internal consistency of the memory arena has been destroyed. 
This is due to a user program changing memory that does not 


belong to it. 


bx,size 
ah,48H 
21H 


; ax:0 is pointer to allocated memo 
: if alloc fails, bx is the largest block available 
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l=. 
~ 7 
“gga Ly 
Free Allocated Memory (Function 49H) 


Segment address of memory 
aréa to be freed 


Return 3 
Carry set: 
AX 
9 = invalid block 
7 = arena trashed 
Carry not set: 
No error 


le 


Function 49H retums a piece of memory to the system pool that was allocated by | 
Function Request 49H. 


9 = invalid block 

The block passed in ES is not one allocated via Function Request 

49H. | 
7 = arena trashed | 


The internal consistency of the memory arena has been destroyed. 


This is due to a user program changing memory that does not 
belong to it. 


Error returns: 
AX 


Example 


mov es, block 
mov ah,49H 
int 21H 


+ See, ee ea _ eee eee 
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Modify Allocated Memory Blocks (Function 4AH) 


AX: 
BX: 
CX: 
DX: 


CH 


Segment address of memory area 


Requested memory area size 


Retum 
Carry set: 
AX 


9 = invalid block 

7 = arena trashed 

8 = not enough memory 
BX 

Maximum size possible 
Carry not set: 

No error 


Function 4AH will attempt to grow/shrink an allocated block of memory. 


Error returns: 


9 = invalid block 


The block passed in ES is not one allocated via this function. 


7 = arena trashed 


The internal consistency of the memory arena has been destroyed. 
This is due to a user program changing memory that does not 


belong to it. 
8 = not enough memory 


There was not enough free memory after the specified block to 
satisfy the growth request. 


mov es, block 
mov bx,newsize 
mov ah,4AH 

int 21H 


; if setblock fails for growing, BX will have the 
; maximum size possible. 


see 
. ° 
tegcee'd 
See stece 
Steg tence 
°° tee seess. 
erodes, 
tee ee eles 
° 
os 
. 
ee stece 
eccteese 
PPA 
ec tee sheets 
tolPoetecee 
. . 
*e ° . 
torte 
soc teedss 
Pees seston ceag 
*e © ° 
° oe 


Sig 
. 
o,*e 
. *. 
Sec es 
*o 
eete 


~-—-*" 


—_— et _ - 
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Load and Execute a Program (Function 4BH) 


AX: Call 
Cx: DS:DX 
Dx: Pointer to pathname 
ES:BX 
Pointer to parameter block 
AL 


OO = Load and execute program — 
03 = Load program 


Return 
Carry set: 
AX 


1 = invalid function 
10 = ban environment 
11 = bad format 
8 = not enough memory 
= file not found 
Carry not set: 
No error 


This function allows a program to load another program into memory and (default) 
begin execution of it. DS:DX points to the ASCIZ name of the file to be loaded. 
ES:BX points to a parameter block fortheload. — 


A function code is passed in AL: 
AL Function 


eae 30 SS SO 2S OF oS CE ar GE 


QO Load and execute the program. A program header is established for the 
program and the terminate and CONTROL-C addresses are set to th 
instruction after the EXEC system call. . 


3 Load (do not create) the program header, and do not begin execution. 
This is useful in loading program overlays. 


ee es SS SES ee 


ne ee. es ee a ee on eee 


a ee ee 


Chapter One 


For each value of AL, the block has the following format: 
AL = 0 —> load/execute program 
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ce be tee 
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Note that all open files of a process are duplicated in the child process after an 
EXEC. This is extremely powerful; the parent process has control over the 
meanings of stdin, stdout, stderr, stdaux and stdpm. The parent could, for 
example, write a series of records to a file, open the file as standard input, open a 
listing file as standard output and then EXEC a sort program that takes its input 
from stdin and writes to stdout. 


Also inherited (or passed from the parent) is an ‘‘environment.” This is a block of 
text strings (less than 32K bytes total) that convey various configurations 
parameters. The format of the environment is as follows: 


(paragraph boundary) 


BYTE ASCiZ string 1 


BYTE ASCIZ string n 


7 


BYTE ASCIZ string 2 | 


Fe. 
Lee? 


dag OF 
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Typically the environment strings have the form: 


parameter=value 


For example, COMMAND.COM might pass its execution search path as: 
PATH=A:\ BIN;B:\ BASIC\LIB 


A zero value of the environment address causes the child process to inherit the 
parent’s environment unchanged. 


Error retums: 
AX 
1 = invalid function 
The function passed in AL was not 0, 1 or 3. 
10 = bad environment 
The environment was larger than 32Kb. 
11 = bad format 
The file pointed to by DS:DX was an EXE format file and contained 
information that was internally inconsistent. 
8 = not enough memory 
There was not enough memory for the process to be created. 
2 = file not found 
The path specified was invalid or not found. 


Example 


Ids dx,name 
les bx, bik 
mov ah, 4BH 
mov al, func 
int 21H 


~ ono ew eS ee ee 8 eee 
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Terminate a Process (Function 4ChH) 


AX: Call 
BX: AH = 4CH 
CX: ~ eee 
DX: a es 
Patum 
| BP None 
ee 


Function 4CH terminates the current process and transfers control to the invoking 


process. In addition, a retum code may be sent. All files open at the time are 
closed. 


This method is preferred over all others (Interrupt 20H, UMP 0) and has the 
advantage that CS:0 does not have to point to the Program Header Prefix. 


Error returns: 
None. 


| 


mov al, code 
mov ah, 4CH 


| Example 
| 
! int 21H 


2S SS SS CS eS O88 SESS OSE «ee es © 0 ees 


_ ree ee ee 0 ees cee ee ee 0 ES ETE ESET SEE CRE | ees ome © ame en - we 


F cat Le 7 
/ E45 


Wage 
so Lh 
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Retrieve the Return Code of a Child (Function 4DH) 


Call . 
AH = 4DH 


Retum 
AX 
Exit code 


Function 4DH retums the Exit code specified by a child process. It retumns this Exit 
code only once. The low byte of this code is that sent by the Exit routine. The high 
byte is one of the following: 


0 — Terminate/abort 

1 — CONTROL-C 

2 — Hard error 

3 — Terminate and stay resident 


Error returns: 
None. 


Example 


mov ah, 4DH 
int 21H 
- ax has the exit code 


- oe | had en meee oe eee ee 


8 Stee wwe eee eee & om 


—-. 


— 


ee eee 


me mee ee ee ee 


es eee 
ee ee ee ae ee 


Chapter One Systems Calls Page 1-129 


Find Match File (Function 4EH) 


Call 
AH = 4EH 
DS:DX 
Pointer to pathname 
Cx 
Search attributes 


Retum 
Carry set: 
AX 


2 = file not found 

18 = nomore files 
Carry not set: 

No error 


Function’ 4EH takes a pathname with wild-card characters in the last component 
(passed in DS:DX), a set of attributes (passed in CX) and attempts to find all files 
that match the pathname and have a subset of the required attributes. A datablock 
at the current DMA is written that contains information in the following form: 


find_buf_reserved DB 21 DUP(?); Reserved’ 


find__buf__attr DB ? =: attribute found 
find__buf__time DW ? :time 
find__buf__date DW :date 


find__buf__size__1 DW ?- ; low(size) 
find_buf_size_h DW ?_ ;high(size) 
find_buf_pname DB 13DUP(?);packedname 
find__buf ENDS 
| *Reserved for DOS use on subsequent find__nexts 
To obtain the subsequent matches of the pathname, see the description of 
Function 4FH. 


Error returns: 


2 = file not found 
The path specified in DS:DX was an invalid path. 
18 = no more files 
There were no files matching this specification. 


~e<ee Oe awe eT ee ee 
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Example 


mov ah, 4EH 
ids dx, pathname 
mov cx, attr 


int 21H 
- dma address has datablock 


ome a 


| Chapter One Systems Calls ———= 
| Step Through a Directory Matching Files (Function SFP?) 
AX: eesA Bes Call 
Bx: | BH | BL AH = 4FH 
CX: 
OX — 
Carry set: 
AX 
18 = nomore files 
Carry not set: 
No error 
—_ oe 


| - Function 4FH finds the next matching entry in a directory. The current DMA 


address must point at a block returned by Function 4EH 


_ 


* 
Oe om — <——eeeeo—s O~ 


- Error retums: 
AX 
18 = nomore files 


oe oe eo 


(see Function 4E4). 


ee oe te ee ane ew OO 


~ 


There are no more files matching this pattern. 


Example 


- dma points at area returned by Function 4-H 


mov ah, 4FH 
int 21H 
‘next entry is at dma 


: 


a 


rT LIS RG GI LIED IC NOTICE IIT LLE LE CSL EL LOOT ELE LIED 


T° 8s = $ ‘ 
Fs ge Spee sae 7 oat O89 redod : 
ie Spee see ME OES IGE ab aes, Mere ther ae 


[Bike 


Usd. 
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Retum C 


The curre 


Error 


urrent Setting of Verify After Write Flag (Function 54H) 
Call 
AH = 54H 


Retum 
AL 
Current verify flag value 


at value of the verify flag is returned in AL. 


retums: 


None. 


Example 


Mov 
int 
al 


ah, 54H 
21H | 
is the current verify flag value 


ee Sct nee wae ee “+ 


—_ — cers Saisie en ene eon ARES eA STE SS “<--~ - 


- SF ne ee ee enn mn ee at ene ee ee A CAMELS ST oto ee 


Bie hh 
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Call 

AH = 56H 

DS:DX 
Pointer to pathname of 
existing file 

ES:DI 
Pointer to new pathname 


Return 
Carry set: 
AX 


2 = file not found 

17 = not same device 

5 = access denied 
Carry not set: 

No error 


Function 56H attempts to rename a file into another path. The paths must be on 


the same device. 
Error retums: 


2 = file not found 
__ The file name specified by DS:DX was not found. 
17 = not same device 
, The source and destination are on different drives. 

5S = access denied | 
The path specified in DS:DX was a directory or the file specified 
by ES:DI exists or the destination directory entry could not be 
created. | 


Example 


Ids dx, source 
les _ di, dest 
mov ah, 56H 
int 21H 
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00 = get date and time 
O01 = set date and time 
BX 

File handle 
CX (if AL = 01) 

Time to be set 
DX (if AL = 0) 
Date to be set 


Retum 
Carry set: 
AX 
1 = invalid function 
6 = invalid handle 
Carry not set: 

, : No error 


CX/DX set if function 0 


Function 57H retums or sets the last-write time for a handle. These times are not 
recorded until the file is closed. 


A function code is passed in AL: 
AL Function 


O =Retum the time/date of the handle in CX/DX 
1 Set the time/date of the handle to CX/DX 


Error returns: 
AX 
1 = invalid function 
The function passed in AL was not in the range 0:1. 
6 = invalid handle 
The handle passed in BX was not currently open. 


Example 


mov ah, 57H 
mov al, func 
mov bx, handle 
; if al = 1 then next two are mandatory 
mov cx, time 
mov dx, date 
int 21H 
; if al = O then cx/dx has the last write time/date 
‘ for the handie. 


Qe 
‘ = } ae, 
- — U< 
YAS 
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1.8 MACRO DEFINITIONS FOR ADVANCE DOS SYSTEM CALL EXAMPLES 
NOTE 


These macro definitions apply to system cali examples 
OOH through 57H. 


J 
oPERATAIVeeeerxetcaesevwe 


; Interrupts 
PPRRAALALELELIC EL otf | 
5 

, 


‘“ABS__DISK__READ 
abs__disk__read macro disk,buffer,num__sectors, first__sector 


mov al,disk 

mov bx, offset buffer 

mov cx,num__sectors 

mov dx, first__sector 

int 37 ‘interrupt 37 
poof 

endm 


‘-ABS__DISK__WRITE 
abs__disk__write macro disk,buffer,num__sectors, first__sector 


mov al,disk 
mov bx, offset buffer 
mov cx,num__sectors 
mov dx, first__sector 
int 38 ‘interrupt 38 
popf 
endm 
stay__resident macro last__instruc ‘“STAY__RESIDENT 
mov dx, offset last__instruc 
inc ‘dx 
int 39 ‘interrupt 39 
endm 
- Functions 
read_kbd__and__echo macro ‘-READ__KBD_AND__ECHO 
mov ah,1 ‘function 1 
int 33 , 
endm 
display_char macro character ‘DISPLAY__CHAR 


mov di,character 
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mov 
int 
endm 


aux input macro 
mov 
int 
endm 


aux output macro 
MOV 
int 
endm 
page 
print__char macro 
mov 
mov 
int 
endm 
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ah,2 
30 


ah,3 
GHG 


ah,4 
33 


character 
di,character 
ah,5 

eH 


dir__console__io macro switch 


MOV 
mov 
int 
endm 


dl, switch 
ah,6 
30 


dir__console__input macro 


mov 
int 
endm 


read__kbd macro 
mov 
int 
endm 


display macro 
mov 
Mov 
int 
endm . 


get__string macro 
mov 
mov 
mov 
mov 
int 
endm 


ah,8 
3c 


string 


dx, offset string 


ah,9 
33 


limit, string 
string, limit 
string, limit 


dx,offset string 


ah,10 
a3 


check__kbd__status macro 


Mov 
int 
endm 


flush_and__read__kbd 


ah,11 
33 


macro switch 


‘function 2 


-AUX INPUT 
‘function 3 


‘AUX__OUTPUT 


‘function 4 


-PRINT__CHAR _ 


‘function 5 


yr ae 
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‘DIR__CONSOLE__|O 


‘function 6 


-DIR__CONSOLE_ INPUT 


‘function 7 


‘READ_KBD 


‘function 8 


‘DISPLAY 


‘function 9 


-GET__STRING 


‘function 10 


-CHECK__KBD__STATUS 


‘function 11 


-FLUSH_AND__READ__KBD 


= 


AA iE 
US) 
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mov 
mov 
int 
endm 


reset__disk macro 

mov 

int 

endm 
1» Page 
select__disk macro 

mov 

mov 

int 

endm 
open macro 
mov 
mov 
int 
endm 
close macro 
mov 
mov 
int 
endm 


search__first macro 
mov 
mov 
int 
endm 


search__next macro 
mov . 
mov 
int 
endm 


delete macro 
mov 
Mov ; 
int 
endm 


read__seq macro 
Mov 
mov 
int 
endm 
write__seq macro 


MOV 
MOV 
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al, switch 
ah,12 ‘function 12 
6 
-RESET DISK 
ah,13 ‘function 13 
33 
disk ‘SELECT_ DISK 
di,disk{—65] 
ah,14 ‘function 14 
a3 
fcb “OPEN 
dx, offset feb 
ah,15 ‘function 15 
a5 1 
fob ‘CLOSE 
dx, offset feb 
ah,16 ‘function 16 
33 
feb ;SEARCH_FIRST 
dx, offset feb 
ah,17 ‘function 17 
33 
fcb ;SEARCH_NEXT 
dx, offset feb 
.ah,18 ‘function 18 
33 
fcb ‘DELETE 
dx, offset feb 
ah,19 ‘function 19 
a3 
feb FREAD_SEQ 
dx, offset fcb 
ah,20 ‘function 20 
33 
fcb ;WRITE__SEQ 
dx, offset fob 
ah,21 ‘function 21 
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int 
endm 


Create macro 
mov 
mov 
int 
endm 

rename macro 
mov 
mov 
int 
endm 


Current__disk macro 
mov 
int 
endm 


set__dta macro 
mov 
mov 
int 
endm 


alloc__table macro 
Mov 
Int 
endm 


read__ranmacro 
mov 
Mov 
int 
endm 


write__ran macro 
Mov 
mov 
int 
endm 


file__size macro 
mov 
mov 
int 
endm 


Sset__relative record 
se mov 
mov 
int ™ 
endm 


“page 
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33 


fcb 

dx, offset feb 
ah,22 

33 


fcb,newname 
dx, offset feb 
ah,23 

33 


ah,25 
33 


buffer 

dx, offset buffer 
ah,26 

33 


ah,27 
oo 


fob 

dx, offset feb 
ah,33 

33 


fob 

dx, offset feb 
ah,34 

33 


feb 

dx, offset feb 
ah,35 

33 


macro feb 
dx, offset feb 
ah,36 

Jc 


‘CREATE 


‘function 22 


RENAME 


‘function 23 


;CURRENT__DISK 


‘function 25 


;SET_DTA 
‘function 26 


;ALLOC__TABLE 


‘function 27 


-READ_ RAN 
‘function 33 


-;WRITE__RAN 
‘function 34 


‘FILE SIZE 
‘function 35 


SET__RELATIVE_RECORD 


‘function 36 
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set__vector macro interrupt,seg__addr,off_addr ;:SET_VECTOR / ones 
<——T 


push ds 
mov ax,seg__addr 
MOV ds,ax Ct e 
mov dx,off__addr 
mov al,interrupt 
mov ah,37 ‘function 37 
int | 
endm 

create_rog_eg macro seqg_addr ;CREATE_PROG_ SEG 
mov dx,seq__addr 
mov ah,38 ‘function 38 
int 33 
endm 

ran__block__read macro fcb,count,rec__ size ‘-RAN_ BLOCK_READ 
mov dx, offset feb 
mov Cx,count 
mov word ptr feb[14],rec__size 
mov ah,39 ‘function 39 
int S33 
endm 

ran__block__write macro fcb,count,rec__size ;RAN__BLOCK__WRITE 
mov dx, offset feb 
mov cx,count 
mov word ptr fcb[14],rec__size 
mov ah,40 ‘function 40 
int ao 
endm 

parse macro filename,fcb ‘PARSE 
mov si,Offset filename 
mov di,offset feb 
mov di, offset fob 
push es 
push ds 
pop es 
mov al,15 
mov ah,41 function 41 
int 33 
pop es 
endm 

get__date macro ;GET__DATE 
mov ah,42 ‘function 42 
int. 
endm 

;;page 

set__date macro year, month,day ,SET__DATE 
mov, cx, year 
mov dh,month 
mov dl day 
mov ah,43 ‘function 43 


int | 


UL | 
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endm 
get__time macro ;GET_ITME 
mov ah,44 ‘function 44 
int 33 
endm 
set__time macro hour,minutes,seconds,hundrecths 
Mov ch,hour 
mov cl,minutes 
Mov dh,seconds 
mov di,hundredths 
mov ah,45 ‘function 45 
int a3 
endm 
verify macro switch VERIFY 
mov al,switch 
mov ah,46 ‘function 46 
int oo 
endm 
- General 
move__string macro source,destination,num__bytes 
-MOV__STRING 
push es 
mov ax,ds 
mov es ,ax 
assume es:data 
mov si,offset source 
mov di,offset destination 
mov cx,num__bytes 
rep movs €s:destination,source 
assume es:nothing 
Pop es 
endm 
convert macro value, base,destination ‘CONVERT 
local table, start 
jmp ; start 
table db “0123456789ABCDEF” 
Start: mov ai, vaiue 
xor ah,ah : 
xor bx, bx 
div base 
mov bial 
mov al,cs:table[bx] 
mov destination,al 
mov blah 


mov al,cs:table[bx] 


eee cemccep + 


—_——— 
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_mov_ _ destination[1],al ne fae 
endm ; 
11 page 
convert__to__binary macro string,number,value 
;CONVERT__TO_ BINARY 
local ten,start,calc,mult,no__ mult 
jmp start 
ten db 10 
Start: mov value,O 
xor ox.Gx 
mov cl number 
xor Si,si 
Calc: xor ax ,ax 
mov al,string[si] 
sub al,48 
cmp cx,2 
jl no__mult 
push cx 
dec Cx 
mult: mul cs:ten 
loop mult 
Pop cx 
no__mult: add value ,ax 
inc Si 
loop calc 
endm 
convert__date macro dir__entry 
mov dx,word ptr dir__entry[25] 
mov cl,5 | Q t 
(ral C ® 
shr dclo —-——__--> se adie 
mov dh,dir__entry(25] 
and dh,1fh i , 
xor Bo Fe C 3c — = 
mov cl,dir__entry(26] ; | 
shr or > fren, 
add cx, 1980 Ad ES it 
endm eo 


SS” 
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1.9 EXTENDED EXAMPLE OF ADVANCE DOS SYSTEM CALLS 


Wie OISK DUMP 


, 
seh 
= 


sectors. per__read 


equ 0 
equ 1 
equ 9 
equ 13 
equ 32 
equ 46 
equ 126 


INCLUDE B:CALLS.EQU 


subtt! DATA SEGMENT 
Dage + 
data 


input__butfer 
output__buffer 


start__prompt 


segment 


db 9 dup(512 dup(?)) 
db 77 dup(‘' "’) 

db ODH,OAH,‘‘S”’ 

db “Start at sector: $” 


sectors__prompt db ‘‘Number of sectors: $”’ 
continue__prompt db “RETURN to continue $” 
header db ‘Relative sector $’’ 
end__string db ODH,OAH,OAH,07H,"*ALL DONES”’ 
crif db ODH,QAH,‘'S” 
table db ‘0123456789ABCDEF$” 
ten db 10 
Sixteen db 16 
Start__sector dw 1 ; 
secitor__num label byte 
sector__number dw 0 
sectors__to__dump dw sectors__per__read 
sectors__read dw 0 
Ouffer label byte 
max__length db 0 
current__length db 0 
digits db 5dup(?) 
data ends 
subtt!l STACK SEGMENT 
page + 
Stack segment stack 

dw 100 dup(7?) 
Stack__top label word 

ends 


stack 


subttl MACROS 
page + 
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INCLUDE B:CALLS.MAC 
‘BLANK LINE 
blank__line macro number 
local print__it 
push Cx 
Call clear__line 
: mov cx,number 
print__it: display output__buffer 
loop print__it 
pop Cx 
endm 
subttl ADDRESSABILITY 
page + 
code segment 
assume cs:code,ds:data,ss:stack 
Start: mov ax,data 
mov ds ,ax 
mov ax,stack 
mov SS,ax 
mov sp,offset stack__top 
jmp main__procedure 
subttl PROCEDURES 
page + 
‘ PROCEDURES 
‘READ_ DISK oe 
read__disk proc; 
cmp sectors__to__dump,zero 
jle done 
mov bx, offset input__buffer 
mov - dx,start__sector 
mov al,disk__b 
mov cx,sectors__per__read 
cmp cx,sectors__to__ dump 
jle get__sector 
mov cx,sectors__to__dump 
get__sector: push Cx 
int disk__read 
popf 
Pop Cx 
sub sectors__to__dump,cx 
add Start__sector,cx 
mov sectors__read,cx 
xor Si,Si 
done: ret 
read__disk endp 
‘-CLEAR__LINE 
clear__line proc; 
push cx 
Mov Cx,17 
xor bx, bx 
move__blank: mov output__buffer[bx],/ ’ 
inc bx 


o> CS 


+ coe nee ae eee 


ete ee MGA 


clear__line 


-PUT__ BLANK 
put__blank 


put__blank 


ry 
’ 


setup 


setup 


‘CONVERT__LINE 
conven__line 


convert__it: 
display__ascii: 
Printable: 


non__printable: 


convert__line 


er we 
ret 
endp 


proc; 

mov output__buffer{dl],** 
inc di 

ret 

endp 


proc; 
display start_prompt 


get__string 4,buffer 

display rif 
convert__to__binary digits, 
current__length,start__sector 
Mov ax,start__sector 
mov sector__number,ax 
display sectors__prompt 
get_string 4,buffer 
convert__to__binary digits, 
current__length,sectors__to__dump 
ret 


endp 

proc; 

push Cx 

mov di,9 

mov cx,16 

convert input__buffer(si],sixteen, 
output__buffer(di] 

inc Si 

add di,2 

Call put__blank 

loop convert_it 

sub si,16 

mov Cx. 16 

add di,4 

mov output__buffer(di] period 
cmp input__buffer{si], blank 
{l non-printable 

cmp input__uffer{si], tilde 

ig non__printable 

mov di, input__buffer(si] 
mov output__buffer(di],dl 
inc si 

inc di 

loop display__ascii 

pop cx 

ret 


a 


Chapter One 


‘DISPLAY__SCREEN 
display__screen proc; 
push 
call 
mov 
-| WANT length header 
dec 
‘minus 1 in cx 
xor 
move__ header: MOV 
mov 
inc 
loop 


convert 
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CX 
clear__ line 


cx,17 
Cx 


di,di 

al, header(di] 
output__buffer(di],al 
di 
move__header ‘FIX THIS! 


sector__num(],sixteen, 


output__b uffer(di] 


add 


di,2 


convert sector__num,sixteen, 
output__b uffer(di] 


add di,2 
convert sector__num,sixteen, 
output__b uffer(di] 
display output__buffer 
blank__line 2 
Mov cx,16 
dump__it: Call clear__line 
call convert__line 
display output__buffer 
loop dump_ it 
blank__line 3 
display continue_prompt 
get__char__no__echo 
display crif 
pop Cx 
ret 
display__screen endp 
- END PROCEDURES 
subttl MAIN PROCEDURE 
page + 
main__procedure: call setup 
check__done: cmp sectors__to__dump,zero 
jng ail__ done 
Call read_ disk 
mov cx,sectors__read 
display__it: call display__screen 
call display__screen 
inc sector__number 
loop display__it 
jmp check__done 
all__done: display end__string 
get__char__no__echo 
code ends 


end 


start 


———, 


the 
Uke 
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CHAPTER TWO 
ADVANCE DOS 2.11 DEVICE DRIVERS 


2.1 WHAT IS A DEVICE DRIVER? 

A device driver is a binary file with all of the code in it to manipulate the hardware 
and provide a consistent interface to Advance DOS. In addition, it has a special 
header at the beginning that identifies it as a device, defines the strategy and 
interrupt entry points, and describes various attributes of the device. 


NOTE 


For device drivers, the file must not use the ORG 
100H (like .COM files). Because it does not use’ 
the Program Segment Prefix, the device driver is 
simply loaded; therefore, the file must have an 
origin of zero (ORG 0 or no ORG statement). 


There are two kinds of device drivers. 
1. Character device drivers 


re Block device drivers 


Character devices are designed to perform serial character !/O like 
CON, AUX, and PRN. These devices are named (i.e., CON, AUX, 
CLOCK, etc.), and users may open channels (handles or FCBs) to do 
I/O to them. 


Block devices are the ‘‘disk drives’ on the system. They can perform random !/O 
in pieces called blocks (usually the physical sector size). These devices are not 
named as the character devices are, and therefore cannot be opened directly. 
Instead they are identified via the drive letters (A:, B:, C:, etc.). 


Block devices also have units. A single driver may be responsible for 
one or more disk drives. For example, block device driver ALPHA may 
be responsible for drives A:,B:,C: and D:. This means that it has four 
units (0-3) defined and, therefore, takes up four drive letters. 
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The position of the driver in the list of all drivers determines which units 
correspond to which driver letters. If driver ALPHA is the first block driver in the 

device list, and it defines 4 units (0-3), then they will be A:,B:,C: and D:. If BETA is 

the second block driver and defines three units (0-2), then they willbe E:,F:and PHA 
___G:, and so on, Advance DOS 2.11 is not limited to 16 block device units, as__ 
previous versions were. The theoretical limit is 63 (26 - 1), butitshouldbe noted 

that after 26 the drive letters are unconventional (such as ], \, and* ). | 


NOTE 


Character devices cannot define multiple units 
because they have only one name. 


jas 
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2.2 DEVICE HEADERS 

A device header is required at the beginning of a device driver. A device header 

looks like this: 


DWORD pointer to next device 
(Must be set to —1) 


WORD attributes 
Bit 15 = 1 if char device 0 is blk 
if bit 15 is 1 
Bit O = 1 if current sti device 
Bit 1 = 1 if current sto output 
Bit 2 = 1 if current NUL device 
Bit 3 = 1 if current CLOCK dev 
Bit 4 = 1 if special 
Bits 5-12 Reserved; must be set 
to 0 
Bit 14 is the IOCTL bit 
Bit 13 is the NON IBM FORMAT bit 


A re ee te 


WORD pointer to device strategy entry 
point 


WORD pointer to device interrupt entry 
point 


8-BYTE character device name field 
Character devices set a device name. 
For block devices the first byte is 

the number of units 


Figure 2. Sample Device Header 


Note that the device entry points are words. They must be offsets from the same 
segment number used to point to this table. For example, if XXX:YYY points to the 
start of this table, then XXX:strategy and XXX:interrupt are the entry points. 


2.2.1 Pointer to Next Device Field 

The pointer to the next device header field is a double word field (offset followed 
by segment) that is set by Advance DOS to point at the next driver in the system 
list at the time the device driver is loaded. It is important that this field be set to —1. 
prior to load (when it is on the disk as a file) unless there is more than one device 
driver in the file. If there is more than one driver in the file, the first word of the 
double word pointer should be the offset of the next driver's Device Header. 
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NOTE 


If there is more than one device driver in the .COM 
file, the last driver in the file must have the pointer 
to the next Device Header field set to —1. 


2.2.2 Attribute Field 

The attribute field is used to tell the system whether this device is a block or 
character device (bit 15). Most other bits are used to give selected character 
devices certain special treatment. (Note that these bits mean nothing on a block 
device). For example, assume that a user has a new device driver that he wants 
to be the standard input and output. Besides installing the driver, he must tell DOS 
that he wants his new driver to override the current standard input and standard 
output (the CON device). This is accomplished by setting the attributes to the ~~ 
desired characteristics, so he wouid set bits 0 and 1 to 1 (note that they are 
separate!). Similarly, a new CLOCK device could be installed by setting that 
attribute. (Refer to Section 2.7, ‘“The CLOCK Device,” in this chapter for more 
information.) Although there is a NUL device attribute, the NUL device cannot be 
reassigned. This attribute exists so that DOS can determine if the NUL device is 
being used. 


The NON IBM FORMAT bit applies only to block devices and affects the operation _. 
of the BUILD BPB (Bios Parameter Block) device call. (Refer to Section 2.5.3, 
“MEDIA CHECK and BUILD BPB,”’ for further information on this call). 

The other bit of interest is the IOCTL bit, which has meaning on character and | OCT L 
block devices. This bit tells DOS whether the device can handle control strings 

(via the IOCTL system call, Function 444). 


2 ere aeons a ow 


lf a driver cannot process control strings, it should initialty set this bit to 0. This tells 
DOS to return an error if an attempt is made (via Function 44H) to send or receive 
control strings to this device. A device which can process control strings should — 
initialize the [OCTL bit to 1. For drivers of this type, DOS will make calls to the 
IOCTL INPUT and OUTPUT device functions to send and receive IOCTL strings. 


— eee eee ee a we es 
eo my °=st = ee — et — r 


i, 


/ 


‘on oar 
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The IOCTL functions allow data to be sent and received by the device for its own 
use (for example, to set baud rate, stop bits, and form length), instead of passing 
data over the device channel as does a normal read or write. The interpretation of 
the passed information is up to the device, but it must not be treated as a normal 
|/O request. 


2.2.3 Strategy And Interrupt Routines 

These two fields are the pointers to the entry points of the strategy and interrupt 
routines. They are word values, so they must be in the same segment as the 
Device Header. 


2.2.4 Name Field 

This is an 8-byte field that contains the name of a character device or the number 
of units of a block device. If it is a block device, the number of units can be put in 
the first byte. This is optional, because DOS will fill in this location with the value 
retumed by the driver’s INIT code. Refer to Section 2.4, ‘Installation of Device 
Drivers’”’ in this chapter for more information. 


2.3 HOW TO CREATE A DEVICE DRIVER 

In order to create a device driver that DOS can install, you must write a binary file 
with a Device Header at the beginning of the file. Note that for device drivers, the 
code should not be originated at 100H, but rather at 0. The link field (pointer to 
next Device Header) should be — 1, unless there is more than one device driver in 
the file.: The attribute field and entry points must be set correctly. 


lf it is a character device, the name field should be filled in with the name of that 
character device. The name can be any legal 8-character filename. 


DOS always processes installable device drivers before handling the default 
devices, so to install a new CON device, simply name the device CON. Remember 
to set the standard input device and standard output device bits in the attribute 
word on anew CON device. The scan of the device list stops on the first match, so 
the installable device driver takes precedence. 


NOTE 


Because DOS can install the driver anywhere in 
memory, care must be taken in any far memory 
references. You should not expect that your driver 
will always be loaded in the same place every 
time. 


Fl 


ress + te ay ee 
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2.4 INSTALLATION OF DEVICE DRIVERS 

DOS 2.11 allows new device drivers to be installed dynamically at boot time. This 
is accomplished by INIT code in the BIOS, which reads and processes the 
CONFIG.SYS file. 


DOS calls upon the device drivers to perform their function in the following 
manner: 


DOS makes a far call to strategy entry, and passes (in a Request 
Header) the information describing the functions of the device 
driver. | 


This structure allows you to program an interrupt-driven device driver. For 
example, you may want to perform local buffering in a printer. 


2.5 REQUEST HEADER 

When DOS calls a device driver to perform a function, it passes a Request 
Header in ES:BX to the strategy entry point. This is a fixed length header, 
followed by data pertinent to the operation being performed. Note that it is the 
device driver’s responsibility to preserve the machine state (for example, save all 
registers on entry and restore them on exit). There is enough room on the stack 
when strategy or interrupt is called to do about 20 pushes. If more stack is 
needed, the driver should set up its own stack. 


The following figure illustrates a Request Header. 


REQUEST HEADER -> 


BYTE length of record 
Length in bytes of this 
Request Header 


BYTE unit code 
The subunit the operation 
is for (minor device) 

(no meaning on character 
devices) 


BYTE comand code 
WORD status 


8 bytes RESERVED 


Figure 3. Request Header 
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2.5.1 Unit Code 

The unit code field identifies which unit in your device driver the request is for. For 
example, if your device driver has 3 units defined, then the possible values of the 
unit code field would be 0, 1, and 2. 


2.5.2 Command Code Field 
The command code field in the Request header can have the following values: 


Command Function 


Code 
0 INIT 
1 MEDIA CHECK (Block only, NOP for character) 
2 BUILD BPB (Block only, NOP for character) 
3 lIOCTL INPUT (Only called if device has IOCTL) 
“ INPUT (read) 
5 NON-DESTRUCTIVE INPUT NO WAIT (Char devs only) 
6 INPUT STATUS (Char devs only) 
7 INPUT FLUSH (Char devs only) 
8 OUTPUT (write) ° 
9 OUTPUT (Write) with verify 
10 OUTPUT STATUS (Char devs only) 
11 OUTPUT FLUSH (char devs only) 
12 lIOCTL OUTPUT (Only called if device has |OCTL) 


2.5.3 MEDIA CHECK And BUILD BPB 
MEDIA CHECK and BUILD BPB are used with block devices only. - 


DOS calls MEDIA CHECK first for a drive unit. DOS passes its current media 
descriptor byte (refer to the section ‘‘Media Descriptor Byte”’ later in this chapter). 
MEDIA CHECK returns one of the following results: 


Media Not Changed — current BPB and media byte are OK. 


_Media Changed — Current BPB and media are wrong. DOS 
invalidates any buffers for this unit and calls the device driver to 
build the BPB with media byte and buffer. 


Not Sure — if there are dirty buffers (buffers with changed data, 


not yet written to disk) for this unit, DOS assumes the DPB and 
media byte are OK (media not changed). If nothing is dirty, DOS 
assumes the media has changed. It invalidates any buffers for the 
unit, and calls the device driver to build the BPB with media byte 
and buffer. 


Error — If an error occurs, DOS sets the error code accordingly. 
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DOS will call BUILD BPB under the following conditions: 
lf Media Changed is returned 


lf Not Sure is returned, and there are no dirty buffers 


The BUILD BPB call also gets a pointer to a one-sector buffer. What this buffer 
contains is determined by the NON IBM FORMAT bit in the attribute field. If the bit 
is zero (device is IBM format-compatible), then the buffer contains the first sector 
of the first FAT. The FAT ID byte is the first byte of this buffer. NOTE: The BPB 
must be the same, as far as location of the FAT is concerned, for all possible 
media because this first FAT sector must be read before the actual BPB is 
returned. If the NON IBM FORMAT bit is set, then the pointer points to one sector 
of scratch space (which may be used for anything). 


2.5.4 Status Word 
The following figure illustrates the status word in the Request Header. 


1S. 14 1a F2° 11 8. SB Fy «8 Se Oe SB ee UT 


a Sp 2D 
R RESERVED U O ERROR CODE (bit 15 on) 
R Ss N 


The status word is zero on entry andis set by the driver interrupt routine on return. 


Bit 8 is the done bit. When set, it means the operation is complete. For DOS 2.11, 
the driver sets it to 1 when it exits. 


Bit 15 is the error bit. If itis set, then the low 8 bits indicate the error. The errors are: 


Write protect violation 
Unknown Unit 

Drive not ready 
Unknown command 
CRC error 

Bad drive request structure length 
Seek error 

Unknown media 
Sector not found 
Printer out of paper 
Write fault 

Read Fault 

C General failure 


Oreoanraoaahdh— oO 
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Bit 9 is the busy bit, which is the set only by status calls. : 


For output on character devices: \f bit 9 is 1 on return, a write 
request (if made) would wait for completion of a current request. If 
it is O, there is no current request, and a write request (if made) 
would start immediately. 


For input on character devices with a buffer: If bit 9 is 1 on return, 
a read request (if made) would go to the physical device. If it is 0 
on return, then there are characters in the device buffer and a 
read would return quickly. It also indicates that something has 
been typed. DOS assumes all character devices have an input 
type-ahead buffer. Devices that do not have a type-ahead buffer 
should always return busy=0 so that DOS will not continuously 
wait for something to get into a buffer that does not exist. 


One of the functions defined for each device is INIT. This is called only once when 
the device is installed. The INIT routine returns a location (DS:DX), which is a 
pointer to the first free byte of memory after the device driver (similar to “Keep 
Process’’). This pointer method can be used to delete initialization code that is 
only needed once, saving on space. 


Block devices are installed the same way and also return a first free byte pointer 
as described above. Additional information is also returned: 


The number of units is returned. This determines logical device 
names. If the current maximum logical device letter is F at the time 
of the install call, and the INIT routine returns 4 as the number of 
units, then they will have logical names G, H, | and J. This 
mapping is determined by the position of the driver in the device 
list, and by the number of units on the device (stored in the first 
byte of the device name field). 


A pointer to a BPB (BIOS Parameter Block) pointer array is also 
returned. There is one table for each unit defined. These blocks 
will be used to build an internal DOS data structure for each of the 
units. The pointer passed to the DOS from the driver points to an 
array of n word pointers to BPBs, where n is the number of units 
defined. In this way, if all units are the same, all of the pointers can 
point to the same BPB, saving space. Note that this array must be 
protected (below the free pointer set by the return) since an 
internal DOS structure will be built starting at the byte pointed to 
by the free pointer. The sector size defined must be less than or 
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equal to the maximum sector size defined at default BIOS INIT 
time. If it isn’t, the install will fail. 


The last thing that INIT of a block device must pass back is the 
media descriptor byte. This byte means nothing to DOS, but is 
passed to devices so that they know what parameters DOS is 
currently using for a particular drive unit. 


.Block devices may take several approaches; they may be dumb or smart. A 
dumb device defines a unit (and therefore an internal DOS structure) for each 
possible media drive combination. For example, unit 0 = drive 0 single side, unit 1 
= drive 0 double side. For this approach, media descriptor bytes do not mean 
anything. A smart device allows multiple media per unit. In this case, the BPB 
table returned at INIT must define space large enough to accommodate the 
largest possible media supported. Smart drivers will use the media descriptor 
byte to pass information about what media is currently in a unit. 


2.6 FUNCTION CALL PARAMETERS 

All strategy routines are called with ES:BX pointing to the Request Header. The 
interrupt routines get the pointers to the Request Header from the queue that the 
Strategy routines store them in. The command code in the Request Header tells 
the driver which function to perform. 


NOTE 
All DWORD pointers are stored offset first, then 
segment. 
2.6.1 INIT 
Command code = 0 
iN -Eoeo ==> 


13-BYTE Request Header 


BYTE #of units 


DWORD break address 


DWORD pointer to BPB array 
(Not set by character devices) 


Up |e» 


er Y 4 
, CoH + 
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The number of units, break address, and BPB pointer are set by the driver. On 
entry, the DWORD that is to be set to the BPB array (on block devices) points to 
the character after the ‘=' on the line in CONFIG.SYS that loaded this device. 
This allows drivers to scan the CONFIG.SYS invocation line for arguments. 


NOTE 


lf there are multiple device drivers in a single 
.COM file, the ending address returned by the last 
INIT called will be the one DOS uses. It is 
recommended that all of the device drivers in a 
single .COM file return the same ending address. 


2.6.2 MEDIA CHECK 
Command Code = 1 
MEDIA CHECK - ES:BX —> 


13-BYTE Request Header 


BYTE media descriptor from DPB 


BYTE returned 


In addition to setting the status word, the driver must set the return byte to one of 
the following: 


—1 Media has been changed 
0 Don’t know if media has been changed 
1 Media has not been changed 


If the driver can return —1 or 1 (by having a door-lock or other interlock 
mechanism) DOS performance is enhanced because DOS does not need to 
reread the FAT for each directory access. 


% 


| 
at Serer ae ee it PER Senses 
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2.6.3 BUILD BPB (BIOS Parameter Block) 
Command Code = 2 
BUILD BPB - ES:BX —-> 


13-BYTE Request Header 
BYTE media descriptor from DPB 


DWORD transfer address 
(Points to one sector worth of 
scratch space or first sector 

of FAT depending on the value 
of the NON IBM FORMAT bit) 


DWORD pointer to BPB 


If the NON IBM FORMAT bit of the device is set, then the DWORD transfer 
address points to a one sector buffer, which can be used for any purpose. If the 
NON IBM FORMAT bit is 0, then this buffer contains the first sector of the first FAT 
and the driver must not alter this buffer. 


lf IBM compatible format is used (NON IBM FORMAT BIT = 0), then the first 
sector of the first FAT must be located at the same sector on all possible media. -- -- 
This is because the FAT sector will be read BEFORE the media is actually 
determined. Use this mode ff all you want is to read the FAT ID byte. 


In addition to setting status word, the driver must set the Pointer to the BPB on 
retum. 


The information relating to the BPB for a particular piece of media is kept in the 
boot sector for the media. In particular, the format of the boot sector is: 


“Tee "oe ME ae re they tate 


-_— 


me 8 me rr, we rt re i wr es ee ee ws 


| LC. y. 
Chapter Two Advance DOS 2.11 Device Drivers Page 2°13 ‘¢¢b-~ 


ee 


BYTE sectors per allocation unit 


The three words at the end (sectors per track, number of heads, and number of 
hidden sectors) are optional. They are intended to help the BIOS understand the 
media. Sectors per track may be redundant (could be calculated from total size of 
the disk). Number of heads is useful for supporting different multi-head drives 
which have the same storage capacity, but different numbers of surfaces. Number 
of hidden sectors may be used to support drive-partitioning schemes. 


= wuvum 


ovo 


2.6.4 Media Descriptor Byte 

The last two digits of the FAT ID byte are called the media descriptor byte. 
Currently, the media descriptor byte has been defined for a few media types, 
including 51%" and 8’ standard disks. For more information, refer to Section 3.6, 


“DOS Standard Disk Formats.”’ 


Although these media bytes map directly to FAT ID bytes (which are constrained 
to the 8 values F8-FF), media bytes can, in general, be any value in the range 
O-FF. 


ee ee ee ee ss 


ee 


SE 
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9.6.5 READ OF WRITE i eae 
Command codes = 3.4,8,9, and Zz NY 


READ or WRITE — ES:BX (Including iOCiIL) = 


43-BYTE Request Header 
B tor from DPB 


YTE media descrip 


DWORD transfer address 

WORD byte/sector count 

WORD starting sector number 
(Ignored on character devices) 


in addition to setting the status word, the driver must set the sector count to the 
actual number of sectors (OF bytes) transferred. No error check is performed on 
an |OCTL VO call. The driver must correctly set the retumn sector (byte) count to 
the actual number of bytes transferred. 


THE FOLLOWING APPLIES TO BLOCK DEVICE DRIVERS: 


Under certain circumstances the BIOS may be asked to perform awrite operation 
of 64K bytes, which seems to be a ‘wrap around” of the transfer address in the 
BIOS 1/0 packet. This request arises due to an optimization added to the write 
will only manifest on user writes that are within a sector size of 64K 
bytes on files growing past the current EOF. /t /s allowable for the BIOS to 
ignore the balance of the write that “wraps around” ifit so chooses. For example, 
qa write of 4QQ000H bytes worth of sectors with a transfer address of XxXX:1 could 
ignore the last two bytes. A user program can never request an 1/O of more than 
EFFFH bytes and cannot wrap around (even to 0) in the transfer segment. 


Therefore, in this case, the last two bytes can be ignored. 


2.6.6 NON DESTRUCTIVE READ NO WAIT 
Command code = 9 


NON DESTRUCTIVE READ NO WAIT—ES:‘BA> 7 


43-BYTE Request Header 


BYTE read from device 


\f the character device retums busy bit = O (characters in buffer), then the next 
character that would be read is returned. This character is not removed from the 
input buffer (hence the term ‘Non Destructive Read’). Basically, this call allows 
DOS to look ahead one input character. 
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2.6.7 STATUS 
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Command codes = 6 and 10 
STATUS Calls — ES:BX — > 


13-BYTE Request Header 


All the driver must do is set the status word and the busy bit as follows: 


For output on character devices: If bit 9 is 1 on return, a write 
request (if made) would wait for completion of a current request. If 
it is O, there is no current request and a write request (if made) 
would start immediately. 


For input on character devices with a buffer: Areturn of 1 means, 
a read request (if made) would go to the physical device. if itis O 
on return, then there are characters in the devices buffer and a 
read would return quickly. A return of 0 also indicates that the user 
has typed something. DOS assumes that all character devices 
have an input type-ahead buffer. Devices that do not have a 
type-ahead buffer should always return busy = Oso that the DOS 
will not hang waiting for something to get into a buffer which 
doesn’t exist. 


2.6.8 FLUSH 
Command codes = 7 and 11 


FLUSH Calls —ES:BxX— > 


13-BYTE Request Header 


The FLUSH call tells the driver to flush (terminate) all pending requests. This call 
is used to flush the input queue on character devices. 
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2.7 THE CLOCK DEVICE 

One of the most popular add-on boards is the real time clock board. To allow-this 
board to be integrated into the system for TIME and DATE, there is a special 
device (determined by the attribute word) called the CLOCK device. The CLOCK 
device defines and performs functions like any other character device. Most 
functions will be: ‘‘set done bit, reset error bit, retum.’’ When a read or write to this 
device occurs, exactly 6 bytes are transferred. The first two bytes are a word, 
which is the count of days since 1-1-80. The third byte is minutes; the fourth, 
hours; the fifth, hundredths of seconds; and the sixth, seconds. Reading the 
CLOCK device gets the date and time; writing to it sets the date and time. 


p LYS ES 


Chapter Two Advance DOS 2.11 Device Drivers Page 2-17 


2.8.1 AN EXAMPLE OF A DEVICE DRIVER 
The following example illustrates a character device driver program. 


WILE V1T52 CONSOLE FOR 2.11 (Advance 86) 


CCPC COHSSAOHSHETHEHSSHOHSSHSHSSHSHHHHSEHOHSHOHSHSHHTEHHEEK ESE HHEHOSEEBAHeSeeoTESHESHOSHOSHESH FEF OBE EOE SD 


FeO e HS AOSOSEHE SEH SOCEEEC OOOOH COC ESCH O SCOTS OO ESET EFS SEEreROS TERS O RES S OSES Eos 


eseceo4aeeocreaeeveecesceeoeceooeaoeoeeeeaoseeeeoeoeaeeeeeoeoeeceeueesceoeeoesevoeoneeseeeoeeeeveoseveoeeeeveses 


CR=13 ;CARRIAGE RETURN 

BACKSP=8 ;BACKSPACE 

ESC=1BH 

BRKADR=6CH ;(00O6C BREAK VECTOR ADDRESS 
ASNMAX=200 ‘SIZE OF KEY ASSIGNMENT BUFFER 


CODE SEGMENT BYTE 
ASSUME CS:CODE,DS:NOTHING,ES:NOTHING 


CON— CONSOLE DEVICE DRIVER 


CONDEV: ‘HEADER POR DEVICE “CON” 
DW a ae 
DW 10000000000100118 ‘CON IN AND CON OUT 
DW STRATEGY 


DW ENTRY 

DB ‘CON 
' COMMAND JUMP TABLES 
CONTBL: : 

D CONSINIT 

DW EXIT 

DW EXIT 


DW CMDERR 
DW CONSREAD 
DW CONSRDND 
DW EXIT 

DW CONSFLSH 
DW CONSWRIT 
DW EXIT 

DW EXIT 


CMDTABL 
DB A) 
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DW CUU ‘Cursor up 
DB ‘B’ 
DW CUD ‘cursor down 
DB jis 
DW GUF ‘cursor forward 
DB ey 
DW CUB ‘cursor back 
DB fai 
DW CUH ;Cursor position 
DB al 
DW a8, erase display 
DB co 
DW EL erase line 
DB i i 
DW CUP ‘cursor position 
DW fy 
DW PSCP ‘Save cursor position 
DB 
DW PRCP ‘restore cursor position 
DB 'y’ 
DW RM ‘reset mode 
DB ; 
DW SM ‘set mode 
DB 00 
PAGE 


Device entry point 


CMDLEN 


UNIT 2 
CMD e 
STATUS = 
MEDIA. 
TRANS 
COUNT = 
START = 
PTRSAV DD 
STRATP PROC 
STRATEGY: 
MOV 
MOV 
RET 
STRATP ENDP 
ENTRY: 
PUSH 
PUSH 
PUSH 
PUSH 


0 ‘LENGTH OF THIS COMMAND 
1 ‘SUB UNIT SPECIFIER 

2 ‘COMMAND CODE 

3 ‘STATUS 

13 MEDIA DESCRIPTOR 

14 ‘TRANSFER ADDRESS 

18 ‘COUNT OF BLOCKS OR CHARACTERS 
20 ‘FIRST BLOCK TO TRANSFER 

0 

FAR 


WORD PTR CS:[PTRSAV],BX 
WORD PTR CS:[PTRSAV+2],ES 


S| 

AX 
CX 
DX 
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PUSH 
PUSH 
PUSH 
PUSH 
PUSH 


LDS 
MOV 


MOV 
CBW 
MOV 
ADD 
ADD 
CMP 
JA 


LES 


PUSH 
POP 


ASSUME 


JMP 


Qe 22222222 22BS2E 222222222 
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DI ae 
BP 
DS 


ES 
BX 


BX,CS:[PTRSAV] 
CX,WORD PTR DS:[BX].COUNT 
AL,BYTE PTR DS:{[BX].CMD 


-GET POINTER TO I/O PACKET 
‘CX = COUNT 


SIOFFSET CONTBL 
SI,AX 

SI,AX 

AL,11 

CMDERR 


DI, WORD PTR DS:[BX]. TRANS 


CS 
DS 


DS:CODE 


WORD PTR [SI] -GO DO COMMAND 


EXIT — ALL ROUTINES RETURN THROUGH THIS PATH 


BUSSEXIT: 


MOV 

JMP 
CMDERR: 

MOV 
ERRSEXIT: 

MOV 

JMP 
EXITP PROC 
EAT: MOV 
ERR1: LDS 

MOV 


WEVICE SUSY EAI) 
AH,000000118 
SHORT ERA 


AL,3 “UNKNOWN COMMAND ERROR 


AH,10000001B 
SHORT ERR1 


FAR 


AH,00000001B 
BX,CS:[PTRSAV] 
WORD PTR [BX].STATUS,AX :MARK 
OPERATION COMPLETE 


‘MARK ERROR RETURN 
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POP BX 
POP ES 
POP DS 
POP BP 
POP DI 
POP DX 
POP ox 
POP AX 
POP S| 
RET -RESTORE REGS AND RETURN 


BREAK KEY HANDLING 

BREAK: 
MOV CS:ALTAH,3 ‘INDICATE BREAK KEY SET 

INTRET: IRET 
PAGE 

WARNING — Variables are very order dependent, 

so be careful when adding new ones! 

WRAP DB 0 -O0 = WRAP, 1 = NO WRAP 
STATE DW 31 
MODE DB 3 
MAXCOL DB 79 
28/5 DB 0 
ROW DB 0 
SAVCR DW 0 
ALTAH DB 0 ‘special key handling 


CHROUT — WRITE OUR CHAR IN ALUSING CURRENT ATTRIBUTE 


ATTRW LABEL WORD 


ATTR DB 00000111B ‘CHARACTER ATTRIBUTE 
BPAGE DB 0 ‘BASE PAGE 
base dw Ob800h 
chrout: cmp al,13 

jNZ trylf 

Mov ([col],O 

IMp short setit 
trylf: cmp al,10 

|Z if 

cmp al,7 

jNZ tryback 
torom: 

mov bx, [attrw] 

and b1,7 

MoOv ah,14 
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ret5: 
tryDback: 


Outchr: 


outchr1: 


If: 


setit: 


scroll: 


myscroll: 


int 
ret 


cmp 
jnz 
cmp 
jz 
dec 
jmp 


mov 
mov 
mov 
int 
inc 
cmp 
jbe 
cmp 
jz 
dec 
ret 


mov 
inc 
cmp 
jb 
MOV 
Call 


mov 
mov 
xor 
mov 
int 
ret 
Call 
cmp 
jz 
cmp 
jz 
mov 
jmp 


MOV 
MOV 
MOv 
MOV 
MOV 
MOV 
XOFr 

MOV 
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10h 


al,8 
outchr 
{[col},0 
ret5 

[col] 
short setit 


bx, [attrw] 
Cx,1] 


[col] 

al, [maxcol] 
setit 
[wrap],0 
Outchr1 
[col] 


{col],0 


(row] 
[row],24 
setit 
{row],23 
Scroll 


dh,row 
di,col 
bh,bh 
ah,2 
10h 


getmod 
al,2 
myscroll 
al,3 


bp,80 
ax,(base] 
es,ax 
ds,ax 
di,di 
$1,160 


f 
‘ f 
Ne 
i 
4 


\ . 
—_ 
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~ 
. 
; 
‘ 


fs 
\ 
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mOv Cx,23°80 P 2 ae 
cid KK 
cmp ax,0b800h 
4 colorcard 
rep MOvVSW 
mov ax, Dx 
mov cx,bp 
rep stosw 

sret: push cs 
pop ds 
ret 

colorcard: - 
mov dx,3dah 

wait2: In al,dx 
test al,8 
|z wait2 
mov al,25h 
mov dx,3d8h 
out dx,al sturn off video 
rep movsw 
mov ax,Dx 
Mov cx,bp 
rep stosw 
mov dx,3d8h 
out dx,al ‘turn on video 
jmp sret 

GETMOD: MOV AH,15 
INT 16 ;get column information 
MOV BPAGE,BH 
DEC AH 
MOV WORD PTR MODE,AX 
RET 

CONSOLE READ ROUTINE 

CONSREAD: 

JC CONSEXIT 
CONS$LOOP: 
PUSH CX SAVE COUNT 
CALL CHRIN ;GET CHAR IN AL 
POP CX 
STOSB ‘STORE CHAR AT ES:DI 
LOOP CONSLOOP 
CONSEXIT: 
JMP EXIT 


INPUT SINGLE CHAR INTO AL 


CHRIN: XOR 


AX,AX 


rr 
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PRE ie 
XCHG AL,ALTAH ‘GET CHARACTER & ZERO ALTAH 
OR AL,AL 
JNZ KEYRET 
INAGN: XOR AH,AH 
INT 22 
ALT10: 
OR AX,AX ‘Check for non-key after BREAK 
JZ INAGN 
OR AL,AL ‘SPECIAL CASE? 
JNZ KEYRET 
MOV ALTAH,AH oO TORE SPECIAL KEY 
REYREC JAET 


KEYBOARD NON DESTRUCTIVE READ. NO WAIT 
CONS$RDND: 


MO AL,[ALTAH] 
OR AL,AL 
JNZ RDEXIT 
RD1: MOV AH,1 
INT 22 
JZ. CONBUS 
OR AX,AX 
JNZ RDEXIT 
MOV AH,0 
INT 22 
JMP CONSRDND 
RDEXIT: LDS BX,([PTRSAV] 
MOV [BX], MEDIA,AL 
EXVEC: JMP EXIT 
CONBUS: JMP BUSSEXIT 
} KEYBOARD FLUSH ROUTINE 
CONS$FLSH: 
MOV [ALTAH],0 ‘Clear out holding buffer 
PUSH DS 
XOR BP BP 
MOV DS,BP ‘Select segment 0 
MOV DS:BUTE PTR 41AH,1EH ‘Reset KB queue head 
‘pointer 
MOV DS:BYTE PTR 41CH,1EH ‘Reset tail pointer 
POP DS 
JMP EXVEC 
} CONSOLE WRITE ROUTINE 


CONSWRIT: 
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CONSLP: 


COUT: 


OUT G: 


JOXZ 
PUSH 
MOV 
XOR 
INT 
MOV 
POP 


MOV 
INC 
CALL 
LOOP 
JMP 


STi 
PUSH 
PUSH 
POP 
CALL 
POP 
IRET 


PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
PUSH 
CALL 
POP 
POP 
POP 
POP 
POP 
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EXVEC 

CX 

AH,3 ‘SET CURRENT CURSOR POSITION 
BX,BXxX 


16 
WORD PTR [COL],DX 
ox 


AL,ES:[DI] 
DI 

OUTC 
CONSLP 
EXVEC 


‘GET CHAR 


OUTPUT CHAR 
‘REPEAT UNTIL ALL THROUGH 


DS 
CS 
DS 
OUTC 
DS 


AX 
CX 
DX 
Ss] 
DI 
ES 
BP 
VIDEO 
BP 
ES 
DI 
S| 
DX 
CX 


OUTPUT SINGLE CHAR IN AL TO VIDEO DEVICE 


VIDEO: 


i 


Sih: 
S1A: 


MOV 
JMP 


CMP 
JNZ 
MOV 
RET 


CALL 
MOV 
gicai 


SI,OFFSET STATE 
[SH] 


AL,ESC 
SiB 
WORD PTR [S!],OFFSET S2 


‘ESCAPE SEQUENCE? 


CHROUT 
WORD PTR [STATE],OFFSET S1 


Chapter Two 


32: 


S7A: 


MOVCUR: 


SETCUR: 


CUP: 


CUP1: 


CUP2: 


SM: 


CUH: 


Cor: 


CUFT: 


* CUB: 


CE: 


CuUU1: 


S/R E 


PUSH 
CALL 
POP 
MOV 
ADD 
CMP 
JZ 
CMP 
JNZ 
JMP 


CMP 
JZ 
ADD 
MOV 
XOR 
MOV 
INT 
JMP 


MOV 
RET 
SUB 
MOV 
MOV 
RET 
SUB 
MOV 
JMP 


MOV 
RET 


MOV 
JMP 


MOV 
MOV 
MOV 
JMP 


MOV 
JMP 


MOV 
MOV 
JMP 


MOV 
JMP 
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AX 
GETMOD 
AX 


‘BX,OFFSET CMDTABL-3 


BX,3 
BYTE PTR [BX],0 
SiA 

BYTE PTR [BX],AL 
S7A 

WORD PTR [BX +1] 


BYTE PTR [BX],AH 
SETCUR 

BYTE PTR [BX],AL 
DX,WORD PTR COL 


WORD PTR [SI], OFFSET CUP1 


AL,32 
BYTE PTR [ROW],AL 
WORD PTR [SI], OFFSET CUP2 


AL,32 
BYTE PTR [COL],AL 
SETCUR 


WORD PTR [SI], OFFSET S1A 


WORD PTR COL,0O 
SETCUR 


AH,MAXCOL 
AL,1 

BX,OFFSET COL 
MOVCUR 


AX,OOFFH 
CUF1 


AX,00FFH 
BX,OFFSET ROW 
MOVCUR 


AX,23°256+ 1 
CUU1 
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PSCP: 
PRCP: 
ED: 
ei 


=e 
ES 


ERASE: 


EDS: 
RM: 
RM1: 


CONSINIT: 


iscolor: 


setbrk: 


MOV 
MOV 
JMP 


MOV 
MOV 
JMP 


CMP 
JAE 


MOV 
MOV 
JMP 


MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
INT 
JMP 


MOV 
Res 
XOR 
MOV 
JMP 


int 
and 
cmp 
jNz 
Mov 
cmp 
ja 


MOV 
MOV 


XOR 


MOV © 


MOV 
MOV 
MOV 


MOV 
MOV 
MOV 
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AX,WORD PTR COL | 
SAVCR,AX 2 pete, Bx 
SETCUR 7 


AX,SAVCR 
WORD PTR COL,AX 
SETCUR 


BYTE PTR [(ROW],24 
Bi 


CX,WORD PTR COL 
DH,24 
ERASE 


BYTE PTR (COL],0 
CX,WORD PTR [COL] 
DH,CH 

DL,MAXCOL 
BH,ATTR 

AX,0600H 

16 

SETCUR 


WORD PTR [SI], OFFSET RM1 


CX,CX 
CH,24 
aie 


11h 
al,00110000b 
al,00110000b 
iscolor 

[base] ,0b00h ‘look for bw card 
al,00010000b 
setbrk 
[(mode],0 
[maxcol],39 


‘look for 40 col mode 


BX,BX 

DS,BX 

BX,BRKADR 

WORD PTR [BX],OFFSET BREAK 
WORD PTR [BX+2],CS 


BX,29H"4 
WORD PTR [BX],OFFSET COUT 
WORD PTR [BX+2],CS 


~ — a 
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LDS 
MOV 


MOV 
JMP 


CODE ENDS 
END 
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BX,CS:[PTRSAV] 

WORD PTR [BX]. TRANS, OFFSET CONSINIT 
‘SET BREAK ADDRESS 

[BX]. TRANS+2,CS 

EXIT 
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CHAPTER 3 
DOS TECHNICAL INFORMATION 


3.1 DOS INITIALIZATION 

DOS initialization consists of several steps. The ROM (Read Only Memory) 
bootstrap obtains control, and then reads the boot sector off the disk. The boot 
sector then reads the following files: 


lO.SYS 
MSDOS.SYS 


Once these files are read, the boot process begins. 


3.2 THE COMMAND PROCESSOR 


The command processor supplied with DOS (file COMMAND.COM.) consists of 
3 parts: 


: I A resident part resides in memory immediately following 
MSDOS.SYS and its data area. This part contains routines to 
process Interrupts 23H (CONTROL-C Exit Address) and 24H 
(Fatal Error Abort Address), as well as a routine to reload the 
transient part, if meeded. All standard DOS error handling is done 
within this part of COMMAND.COM. This includes displaying 
error messages and processing the Abort, Retry, or Ignore 
messages. 


ZA: An initialization part follows the resident part. During startup, the 
initialization part is given control; it contains the AUTOEXEC file 
processor setup routine. The initialization part determines the 
segment address at which programs can be loaded. It is overlaid 
by the first program COMMAND.COM loads because it is no 
longer needed. 


3. A transient part is loaded at the high end of memory. This part 
contains all of the internal command processors and the batch file 
processor. 


The transient part of the command processor produces the system 
prompt (such as A>), reads the command from the keyboard (or 
batch file) and causes it to be executed. For external commands, 
this part builds a command line and issues the EXEC system call 
(Function Request 4BH) to load and transfer contro! to the program. 


EY 
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3.3 DOS DISK ALLOCATION 
The DOS area is formatted as follows: 


Reserved area — variable size 
First copy of file allocation 
table — variable size 


Second copy of file allocation 
table — variable size 
(optional) 


Additional copies of file 
allocation table — variable 
size (optional) 


Root directory — variable size 
File data area 


Allocation of space for a file in the data area is not pre-allocated. The space is 
allocated one cluster at a time. A cluster consists of one or more consecutive 
sectors; all of the clusters for a file are “chained” together in the File Allocation 
Table (FAT). (Refer to Section 3.5, ‘‘File Allocation Table.’’) There is usually a 
second copy of the FAT kept, for consistency. Should the disk develop a bad 
sector in the middle of the first FAT, the second can be used. This avoids loss of 
data due to an unusable disk. 


3.4 DOS DISK DIRECTORY 
FORMAT builds the root directory for all disks. Its location on disk and the 
maximum number of entries are dependent on the media. 


Since directories other than the root directory are regarded as files by DOS, there 
is no limit to the number of files they may contain. 


All directory entries are 32 bytes in length, and are in the following format (note 
that byte offsets are in hexadecimal): 


0-7 Filename. Eight characters, left aligned and padded, if 
necessary, with blanks. The first byte of this field 
indicates the file status as follows: 


OOH The directory entry has never been used. This 
is used to limit the length of directory searches, 
for performance reasons. 


ete 


e space is 
ynsecutive 
Allocation 
3 uSually a 
3i0p a bad 
vids loss of 


sk and the 


DOS, there 


ormat (note 
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2EH The entry is for a directory. If the second byte iS 
also 2EH. then the cluster field contains the cluster 
number of this directory’s parent directory (OQ000H 
if the parent directory is the root directory). 
Otherwise, bytes 01H through OAH are all spaces, 
and the cluster field contains the cluster number 
of this directory. 


E5H_ The field was used, but it has been erased. 
Any other character is the first character of a filename. 


8-0A Filename extension. 


OB File attribute. The attribute byte is mapped as 
follows (values are in 
hexadecimal): 


01 File is marked read-only. An attempt to open the 
file for writing using the Open File system call 
(Function Request 3DH) results in an error code 
being returned. This value can be used along with 
other values below. Attempts to delete the file with 
the Delete File system call (13H) or Delete a 
Directory Entry (41H) will also fail. 


02 Hidden file. The file is excluded from normal 
directory searches. 


04 System file. The file is excluded from nornal 
directory searches. 


08 The entry contains the volume label in the first 
11 bytes. The entry contains no other usable 
information (except date and time of creation), 
and may exist only in the root directory. 


10  Theentry defines a sub-directory, and is excluded 
from normal directory searches. 
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OC-15 
16-17 


18-19’ 


20 ~=sC Archive bit. The bit is set to ‘‘on’’ whenever the file 
has been written to and closed. 


Note: The system files (IO.SYS and MSDOS.SYS) 
are marked as read-only, hidden, and system 
files. Files can be marked hidden when they are 
created. Also, the read-only, hidden, system, and 
archive attributes may be changed through the 
Change Attributes system call (Function Request 
ASH)... % 


Reserved. 


Time the file was created or last updated. The hour, 
minutes, and seconds are mapped into two bytes as 
follows: 


Offset 17H 
IH [TH|H|HIHIMIM|M 
7 S32 


Offset 16H ; 
IMIMIMIS|SIS{[S|S 
5 4 0 


where: 


H is the binary number of hours (0-23) 
M is the binary number of minutes (0-59) 
S is the binary number of two-second increments 


Date the file was created or last updated. 
The year, month, and day are mapped into two bytes as follows: 


Offset 19H 
IY IYI YIYEY LY IM 
7 1 0 


Offset 18H 
IMIMIM|D |D|O|D{D 
66 64 0 


where: 

Y ts 0-119 (1980-2099) 
M is 1-12 

D is 1-31 
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1A-1B Starting cluster; the cluster number of the first 
cluster in the file. 


Note that the first cluster for data space on all disks is 
cluster O02. 


The cluster number is stored with the least significant 
byte first. 


NOTE 


Refer to Section 3.5.1, “How to Use the File 
Allocation Table,’”’ for details about converting 
cluster numbers to logical sector numbers. 


1C-1F File size in bytes. The first word of this four-byte field is 
the low-order part of the size. 


3.5 FILE ALLOCATION TABLE (FAT) 

The following information is included for system programmers who wish to write 
installable device drivers. This section explains how DOS uses the File Allocation 
Table to convert the clusters of a file to logical sector numbers. The driver is then 
responsible for locating the logical sector on disk. Programs must use the DOS 
file management function calls for accessing files; programs that access the FAT 
are not guaranteed to be upwardly-compatible with future releases of Advance 


DOS. 


The File Allocation Table is an array of 12-bit entries (1.5 bytes) for each cluster 
on the disk. The first two FAT entries map a portion of the directory; these FAT 
entries indicate the size and format of the disk. 


The second and third bytes currently always contain FFH. 


The third FAT entry, which starts at byte offset 4, begins the mapping of the data 
area (cluster 002). Files in the data area are not always written sequentially on the 
disk. The data area is allocated one cluster at a time, skipping over clusters 
already allocated. The first free cluster found will be the next cluster allocated, 
regardless of its physical location on the disk. This permits the most efficient 
utilization of disk space because clusters made available by erasing files can be 
allocated for new files. 
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Each FAT entry contains three hexadecimal characters: 


000 


FF7 


FF8-FFF 
KOK 


If the cluster is unused and available. 


The cluster has a bad sector in it. DOS will not allocate such a 
cluster. CHKDSK counts the number of bad clusters for its report. 
These bad clusters are not part of any allocation chain. 


Indicates the last cluster of a file. 


Any other characters that are the cluster number of the next cluster 


in the file. The cluster number of the first cluster in the file is Kept in 
the file’s directory entry. 


The File Allocation Table always begins on the first section after the reserved 
sectors. If the FAT is larger than one sector, the sectors are contingu@us. Two 
copies of the FAT are usually written for data integrity. The FAT is read into one of 
the DOS buffers whenever needed (open, read, write, etc.). For perlormance 
reasons, this buffer is given a high priority to keep it in memory as long as 


possible. 


3.5.1 How To Use The File Allocation Table 


Use the directory entry to find the starting cluster of the file. Next, to locate each 
subsequent cluster of the file: 


1. 


Multiply the cluster number just used by 1.5 (each FAT entry is 
1.5 bytes long). 


The whole part of the product is an offset into the FAT, pointing to 
the entry that maps the cluster just used. That entry contains the 
cluster number of the next cluster of the file. 


Use a MOV instruction to move the word at the calculated FAT 
offset into a register. 


if the last cluster used was an even number, keep the low-order 
12 bits of the register by ANDing it with FFF; otherwise, keep the 


high-order 12 bits by shifting the register right 4 bits with a SHR 
instruction. 


wee 6 eens -_-——- - =---- - = <2 emree ee) + eee 6 ee = 


Fi 
/ id 
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Chapter Three DOS Technical Information Page 3-7 


on lf the resultant 12 bits are FF8H-FFFH, the file contains no more 
clusters. Otherwise, the 12 bits contain the cluster number of the 
next cluster in the file. 


To convert the cluster to a logical sector number (relative sector, such as that 
used by Interrupts 25H and 26H and by DEBUG): 


q; Subtract 2 from the cluster number. 
2. Multiply the result by the number of sectors per cluster. 


3. Add to this result the logical sector number of the beginning of the 
data area. 


3.6 DOS STANDARD DISK FORMATS 

Ona DOS disk, the clusters are arranged on disk to minimize head movement for 
multi-sided media. All of the space on a track (or cylinder) is allocated before 
moving on to the next track. This is accomplished by using the sequential sectors 
on the lowest-numbered head, then all the sectors on the next head, and so on 
until all sectors on all heads of the track are used. The next sector to be used will 
be sector 1 on head 0 of the next track. 


For disks, the following table can be used: 


Sectors/ FAT size Dir Dir Sectors/ 
Track Sectors Sectors Entries Cluster 


Figure 4. 5Y%’’ Disk Format 


The first byte of the FAT can sometimes be used to determine the format of the 
disk. The following 51/”’ formats have been defined for the Advance 86 based on 
values of the first byte of the FAT. The formats in Table 3.1 are considered to be 
the standard disk formats for DOS. 


me ee ee eee eee 


——— 
acc aa: 
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Table 3.1 DOS Standard Disk Formats 
54 54 5V4 54 8 8 8 
No. sides 1 1 2 2 1 1 - 
Tracks/side 40 40 40 40 if 77 77 
Bytes/sector 512 512 512 512 128 128 1024 
Sectors/track 8 9 8 9 26 26 8 
Sectors/ 
allocation unit 1 1 2 2 4 4 1 
Reserved 
sectors 1 1 ; 4 4 r , 
No. FATs 2 2 2 2 2 2 2 
Root directory 
entries 64 64 112 112 68 68 192 
No. sectors 320 360 640 720 2002 2002 616 
Media Descriptor 
Byte ris FC aa FD FE” FD a 
Sectors for 
1 FAT 1 2 1 2 6 6 2 


* The two media descriptor bytes that are the same for 8"’ disks (FER) is not a 
misprint. To establish whether a disk is single- or double-density, a read of a 
single-density address mark should be made. If an error occurs, the media is 
double-density. 
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CHAPTER 4 
DOS CONTROL BLOCKS AND WORK AREAS 
4.1 TYPICAL DOS.MEMORY MAP 
0000:0000 Interrupt vector table 
0070:0000 1IO.SYS — DOS interface to hardware 


XXXX:0000 MSDOS.SYS — DOS interrupt handlers, service routines 
(Interrupt 21H functions) 


MS-DOS buffers, control areas, and installed device drivers 


XXXX:0000 Resident part of COMMAND.COM — Interrupt handlers for 
Interrupts 22H (Terminate Address), 23H (CONTROL-C Exit 
Address), 24H (Fatal Error Abort Address) and code to reload the 
transient part 


XXXX:0000 External command or utility — (.COM or .EXE file) 
XXXX:0000 User stack for .COM files (256 bytes) 


XXXX:0000 + Transient part of COMMAND.COM — Command interpreter, 
internal commands, batch processor 


AQ00:0000 Top of RAM memory (640k) 
B800:0000 Video RAM (16k) 
FOO0:0000 Advance Cassette Basic (Rom) 
FOOO:E000 BIOS (Rom) 
FFFF:0000 Restart Vector 
t Memory map addresses are in segment:offset format. 
For example, 0090:0000 is absolute address OS00H. 


2. User memory is allocated from the lowest end of available memory ' 
that will meet the allocation request. 


as ae 
np Sa 


ty 
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4.2 DOS PROGRAM SEGMENT 

When an external command is typed, or when you execute a program through the 
EXEC system call, DOS determines the lowest available free memory address to 
use as the start of the program. This area is called the Program Segment. 


The first 256 bytes of the Program Segment are set up by the EXEC system call 
for the program being loaded into memory. The program is then loaded following 
this block. An .EXE file with minailoc and maxalloc both set to zero is loaded as 
high as possible. 


At offset 0 within the Program Segment, DOS builds the Program Segment Prefix 
control block. The program returns from EXEC by one of four methods: 


4 A long jump to offset 0 in the Program Segment Prefix 
2.  Byissuing an INT 20H with CS:0 pointing at the PSP 


3. By issuing an INT 21H with register AH=0 with CS:0 pointing at 
the PSP, or 4CH and no restrictions on CS 


4. By along call to location 50H in the Program Segment Prefix with 
AH=0 or Function Request 4CH 


NOTE 


It is the responsibility of all programs to ensure 
that the CS register contains the segment address 
of the Program Segment Prefix when terminating 
via any of these methods, except Function Request 
4CH. For this reason, using Function Request 
4CH is the preferred method. 


All four methods result in transferring control to the program that issued the 
EXEC. During this returning process, Interrupts 22H, 23H, and 24H (Terminate 
Address, CONTROL-C Exit Address, and Fatal Error Abort Address) addresses 
are restored from the values saved in the Program Segment Prefix of the 
terminating program. Control is then given to the terminate address. If this is a 
program returning to COMMAND.COM, control transfers to its resident portion. If 
a batch file was in process, it is continued; otherwise, COMMAND.COM performs 


? 


ee oe Oe res EE ED SR ES SED SETS 
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a checksum on the transient part, reloads it if necessary, then issues the system 
prompt and waits for you to type the next command. 


When a program receives control, the following conditions are in effect: 


For all programs: 


The segment address of the passed environment is contained at 
offset 2CH in the Program Segment Prefix. 

The environment is a series of ASCII strings (totalling less than 
32K) in the form: 


NAME=parameter 


Each string is terminated by a byte of zeros, and the set of strings 
is terminated by another byte of zeros. The environment built by 
the command processor contains a least a COMSPEC= string 
(the parameters on COMSPEC define the path used by DOS to 
locate COMMAND.COM on disk). The last PATH and PROMPT 
commands issued will also be in the environment, along with any 
environment strings defined with the Advance DOS SET command. 


The environment that is passed is a copy of the invoking process 
environment. If your application uses a ‘‘keep process’”’ concept, 
you should be aware that the copy of the environment passed to 
you is Static. That is, it will not change even if subsequent SET, 
PATH, or PROMPT commands are issued. 


Offset 50H in the Program Segment Prefix contains code to call 
the DOS function dispatcher. By placing the desired function 
request number in AH, a program can issue a far call to offset 50H 
to invoke a DOS function, rather than issuing an Interrupt 21H. 
Since this is a call and not an interrupt, DOS may piace any code 
appropriate to making a system call at this position. This makes 
the process of calling the system portable. 


The Disk Transfer Address (DTA) is set to 80H (default DTA in the 
Program Segment Prefix). 


File control blocks at 5CH and 6CH are formatted from the first 
two parameters typed when the command was entered. If either 
parameter contained a pathname, then the corresponding FCB 
contains only the valid drive number. The filename field will not be 
Valid. 


hb 


/ 
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An unformatted parameter area at 81H contains all the characters 
typed after the command (including leading and imbedded 
delimiters), with the byte at 80H set to the number of characters. If 
the <, >, or parameters were typed on the command line, they 
(and the filenames associated with them) will not appear in this 
area; redirection of standard input and output is transparent to 
applications. 


Offset 6 (one word) contains the number of bytes available in the 
segment. 


Register AX indicates whether or not the drive specifiers (entered 
with the first two parameters) are valid, as follows: 


AL=FF if the first parameter contained an invalid drive 
specifier (otherwise AL=00) 


AH=FF if the second parameter contained an invalid drive 
specifier (otherwise AH=00) 


Offset 2 (one word) contains the segment address of the first byte 
of unavailable memory. Programs must not modify addresses 
beyond this point uniess they were obtained by allocating memory 
via the Allocate Memory system call (Function Request 48H). 


For Executable (.EXE) programs: 


DS and ES registers are set to point to the Program Segment 
Prefix. 


CS,IP,SS, and SP registers are set to the values passed by LINK. 
For Executable (.COM) programs: 


All four segment registers contain the segment address of the 
initial allocation block that starts with the Program Segment Prefix 
control block. 


All of user memory is allocated to the program. If the program 
invokes another program through Function Request 4BH, it must 
first free some memory through the Set Block (4AH) function call, 
to provide space for the program being executed. 


The Instruction Pointer (IP) is set to 100H. 
The Stack Pointer register is set to the end of the program's 


segment. The segment size at offset 6 is reduced by 100H to 
allow for a stack of that size. 


- 
—wer' 
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A word of zeros is placed on top of the stack. This is to allow a user 
program to exit to COMMAND.COM by doing a RET instruction 
last. This assumes, however, that the user has maintained his 
stack and code segments. 


Figure 5 illustrates the format of the Program Segment Prefix. All offsets are in 
hexadecimal. 


(Offsets in hex) 


Long call to DOS 
function dispatcher 
(S bytes)" 


Terminate address CTRL-C exit 
(IP,CS) address (IP) 


Ctrl-C exit Hard error exit address 
address (CS) (IP.CS) 


Oe ee re ee re 


Used by DOS *** 


Formatted Parameter Area 1 formatted as standard unopened 
FOB 6CH os 
Formatted Parameter Area 2 formatted as standard unopened 
____FCB (overlaid if FCB at SCH is opened) 
Unformatted Parameter Area 
___ (default Disk Transfer Area) 


—_— = ee 


Figure 5. Program Segment Prefix 


IMPORTANT 


Programs must not alter any part of the Program 
Segment Prefix below offset 5CH. 
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CHAPTER 5 
.EXE FILE STRUCTURE AND LOADING 
The .EXE files produced by LINK consist of two parts: 
Control and relocation information 
The load module " 
4 


The control and relocation information is at the beginning of the file in an area 
called the header. The load module immediately follows the header. 


The header is formatted as follows. (Note that offsets are in hexadecimal.) 


Offset Contents 

00-01 Must contain 4DH, 5AH. . are 

02-03 Number of bytes contained in last page; this is useful in reading 
overlays. 

04-05 Size of the file in 512 byte pages, including the header. 

06-07 Number of relocation entries in table. tee 

08-09 Size of the header in 16-byte paragraphs. This is used to locate the 
beginning of the load module in the file. eer 

OA-0B Minimum number of 16-byte paragraphs required above the end 
of the loaded program. ee 

O0C-0D Maximum number of 16-byte paragrpahs required above the end 2n the 
of the loaded program. If both minalloc and maxalloc are 0, then the 
program will be loaded as high as possible. tarting 

_OE-OF | Initial value to be loaded into stack segment before starting 

program execution. This must be adjusted by relocation. -ogram 

10-11 Value to be loaded into the SP register before starting program 
execution. 
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12-13 
14-15 


16-17 


18-19 
1A-1B 
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Negative sum of all the words in the file. 


Initial value to be loaded into the IP register before starting 
program execution. 


Initial value to be loaded into the CS register before starting 
program execution. This must be adjusted by relocation. 


Relative byte offset from beginning of run file to relocation table. 


The number of the overlay as generated by LINK. 


The relocation table follows the formatted area described above. This table 
consists of a variable number of relocation items. Each relocation item contains 
two fields: a two-byte offset value, followed by a two-byte segment value. These 
two fields contain the offset into the load module of a word which requires 
modification before the module is given control. The following steps describe this 


process: 


The formatted part of the header is read into memory. Its size is 1BH. 


A portion of memory is allocated depending on the size of the load 
module and the allocation numbers (OA-0B and 0C-0D). DOS 
attempts to allocate FFFFH paragraphs. This will always fail, 
returning the size of the largest free block. If this block is smaller 
than minalloc and loadsize, then there will be no memory error. If 
this block is larger than maxalloc and loadsize, DOS will allocate 
(maxalloc + loadsize). Otherwise, DOS will allocate the largest 
free block of memory. 


A Program Segment Prefix is built in the lowest part of the allocated 
memory. 


The load module size is calculated by subtracting the header size 
from the file size. Offsets 04-05 and 08-09 can be used for this 
calculation. The actual size is downward-adjusted based on the 
contents of offsets 02-03. Based on the setting of the high/low 
loader switch, an appropriate segment is determined at which to 
load the load module. This segment is called the start segment. 


The load module is read into memory beginning with the start 
segment. | 
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The relocation table items are read into a work area. 


Each relocation table item segment value is added to the start 
segment value. This calculated segment, plus the relocation item 
offset value, points to a word in the load module to which is added 
the start segment value. The result is placed back into the.word in 
the load module. 


Once all relocation items have been processed, the SS and SP 
registers are set from the values in the header. Then, the start 
segment value is added to SS. The ES and DS registers are set to 
the segment address of the Program Segment Prefix. The start 
segment value is added to the header CS register value. The 
result, along with the header IP value, is the initial CS:IP to 
transfer to before starting execution of the program. 


mn rs rr nn eee 
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APPENDIX A S/0 
ANSI ESCAPE SEQUENCES ; 
An ANSI escape sequence is a series of characters (beginning with an escape 


character or keystroke) that you can use to define functions to DOS. Specifically 
you can reassign keys, change graphics functions and affect cursor movement. 


This appendix explains how the ANSI escape sequences are defined for DOS 
version 2.11. Examples on how to use ANSI escape sequences are included at 
the end of this appendix. 

Notes: 


1. To use the ANSI sequences you must have loaded the device 
driver ANSI.SYS at boot time by creating a line inthe CONFIG.SYS 
file: device = ANSI.SYS. 


2. The default value is used when no explicit value or a value of zero 
is specified. 


3. | Pn represents ‘‘numeric parameter.” This is a decimal number 
specified with ASCIl digits. 


4. Ps represents ‘selective parameter.’’ This is any decimal number 
that is used to select a subfunction. Multiple subfunctions may be 
selected by separating the parameters with semicolons. 


A.1 CURSOR FUNCTIONS 
The following escape sequences affect the cursor position on the screen. 


CUP — Cursor Position 
ESC LFIZPCHr 
HVP — Horizontal & Vertical Position 


ESC (Pl; res 
CUP and HVP move the cursor to the position specified by the parameters. The 
first parameter specifies the line number, and the second parameter specifies the 


column number. The default value is 1. When no parameters are specified, the 
cursor is moved to the home position. 


CUU — Cursor Up 
ESC[PnA 


This sequence moves the cursor up one line without changing columns. The 
value of Pn determines the number of lines moved. 
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fore. 


The default value for Pnis 1. The CUU sequence is ignored if the cursor is already 


on the top line. — / | 


CUD — Cursor Down 


ESC {Pa 


This sequence moves the cursor down one line without changing columns. The 
value of Pn determines the number of lines moved. The default value for Pn is 1. 
The CUD sequence is ignored if the cursor is already on the bottom line. 


CUF --- Cursor Forward 
bees Pit: 


The CUF sequence moves the cursor forward one column without changing 
lines. The value of Pn determines the number of columns moved. The default 
value for Pnis 1. The CUF sequence is ignored if the cursor is already in the far 


right column. 
CUB — Cursor Backward 


EOC Pap 
This oscapoe saquaencoe movos tho cursor back one column without changing 
lines The value of Pn deatennineas the number of colts moved. The cefaull 
vetltig for brio t Phe CULS sequence is lymored If Wie Cutsut is alteady tri thes fut 
left column. 


DSR -—— Device Status Report. 


ESC L6n 


The console driver will output a CPR sequence (see below) on receipt of the DSR 
escape sequence. 


CPR — Cursor Position report (from console driver to system) 
ESC i Pn-PaR 


The- CPR sequence reports curront cursor position via standard input. The first 
parameter specifies the current line and the second parameter specifies the 
current column. 


SCP — Save Cursor Position 
ESU [Ss 


The current cursor position is saved. This cursor position can be restored with the 
RCP sequence (see below). | 
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RCP — Restore Cursor Position 


Boul t 
This sequence restores the cursor position to the value it had when the console 


driver received 


A.2 ERASING 


The following escape sequences affect erase functions. 


the SCP sequence. 


ED — Erase Display 
ESC {2d 
The ED sequence erases the screen and the cursor goes to the home position. 


EL — Erase Line 


ESC [K 
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Ss] L 


This sequence erases from the cursor to the end of the line (including the cursor 


position). 


A.3 MODES OF OPERATION 


The following escape sequences affect screen graphics. 


SCR — Set Graphics Rendition 
ESC IMS: ui PSim 


The SCR escape sequence invokes the graphic functions specified by the 
parameter(s) described below. The graphic functions remain until the next 


occurrence of an SCR escape sequence. 


Parameter 


Parameter Function 


All Attributes off 
Bold on 
Underscore on 
Blink on 

Reverse Video on 
Concealed on 
Black foreground 
Red foreground 
Green foreground 
Yellow foreground 
Blue foreground 
Magenta foreground 
Cyan foreground 
White foreground 
Black foreground 


Red foreground 


(monochrome displays only) 


(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard) 
(ISO 6429 standard} 
(ISO 6429 standard) 
(ISO 6429 standard) 


ee cere ceeemes 2 cece: eneene seme: we 
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42 Green background (ISO 6429 standard) ae 5 
43 Yellow background (ISO 6429 standard) 3 / ; a 
a Blue background (ISO 6429 standard) 
45 Magenta background (ISO 6429 standard) 
46 Cyan background (ISO 6429 standard) 
47 White background (ISO 6429 standard) 


SM — Set Mode 


ESC [=Psh 
or ESC [=h 
or ESC [=0h 
or esc? 7) 


The SM escape sequence changes the screen width or type to one of the 
following parameters: 


Parameter Parameter Function 


40 x 25 black and white 
40 x 25 colour 
80 x 25 black and white 
80 x 25 colour 


320 x 200 colour 

320 x 300 black and white 
640 x 200 black and white 
wrap at end of line 


NOOO WN OO 


RM — Reset Mode 


ESC ({=Pst 
or ESC [= 1 
or [= 01 
or re ey : 


Parameters for RM are the same as for SM (Set Mode), except that parameter 7 
will reset the wrap at the end of the line mode. 


A.4 KEYBOARD REASSIGNMENT 
Although not part of the ANSI 3.64-1979 or ISO 6429 standard, the following 
keyboard reassignments are compatible with these standards. 


The control sequence is: 


ESO PAPA FRO 
or [ ‘string’; p 
or [Pas "sting sPns Pos sting’ {rnp 
or any other combination of strings and decimal numbers 


The final code in the control sequence (p) is one reserved for private use by the 
ANSI 3.64-1979 standard. 


go Pe ewe } i 
—S==__, bias boos 
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The first ASCII code in the control sequence defines which code is being mapped. 
The remaining numbers define the sequence of ASCII codes generated when 
this key is intercepted. Note that there is one exception: if the first code in the 
sequence is zero (NUL), then the first and second code make up an extended 
ASCIl redefinition. 


Examples: 
1. Reassign the Q and q key to the A and a key (and vice versa): 
ESC | 652810 A becomes Q 
ESo (S731 tsp a becomes q 
EOC (81:65p ~ Qbecomes A 
SSG T1379 7D q becomes a 


Zs Reassign the F10 key to a DIR command followed by a carriage 
return: 


ESCTO;68. "air; tsp 


The 0:68 is the extended ASCII code for the F10 key; 13 decimal isa 
carriage return. 


- Copyright © Microsoft Corp 1981,82,83 
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APPENDIX B-1 soe iT od vee 
SAMPLE RUN mt 


A>edlin hello.asm | Vse Edun to 
Creac i lw 


new file 
*| | 
Example program to demonstrate use of MASM and calling DOS 


: Uses EDLIN, MASM, LINK, EXE2BIN and DEBUG 


i 
* 
* 
. 
:‘*: Prints the msg ‘‘Hello, world” five times over (Neat, Huh?) 
'* 


Moh Wh — 


7:* code segment 
8:* assume cs:code,ds:code,es:code,ss:code 
9:* org 100h - This is to be a.com file 
10: *start: 
11:* movcx,5 ;Howmany times to print message 
12:*pr__loop: 
13:*% movah,9 ;Select DOS function 9 (Print string) 
14:% mov dx, offsetmessage ; dx is set equal to the address of the 


message 
15:* int21h =; Call DOS to print message | 
16:* loop pr__loop ‘test if we are done, if not loop round again. 
17:% int 20h - Exit back to DOS command level 


18:*: 
19:%*message db ‘‘Hello, world”,ODh,0Ah,“$” 
20:* code ends 


21:* end start 
Fo Pe cael ee EQuia 


A>masm 
The Microsoft MACRO Assembler, Version 17. 


~~fAstenble Sevrce 
Source filename [.ASM]: hello ; ; 
Object filename [hello.OBJ]: helio F ‘le no mM 
Source listing [NUL.LST}: nul 
Crosas reference [NUL.CRF}: nul 


Warming Severe 
Errors Errors 
0 0 


_IP=0100 NVUPDIPLNZNAPONC < 


A> link 


Microsoft Object Linker V2.01 (Large) : 
(C) Copyright 1982, 1983 by Microsoft Inc. <S | x, 


Object Modules [{.OBU]: hello 
Run file [HELLO.EXE]: hello 
List file [NUL.MAP]: nul 
Libraries [.LIB]: nul 
Warning: No STACK segment € 


There was 1 error detected. 


A>exe2bin hello.exe hello.com re] 


“ >debug hello.com € 
-r 

AX=0000 BxX=0000 CX=001D DX=0000 SP=FFFE BP=0000 
S!1=0000 DI=0000 DS=096A ES=096A SS=096A CS=096A 


096A:0100 B90500 MOV  CX,0005 


-U : 
semicoion B90500 MOV CX, 0005 Vrescemble So 


096A:0103 B409 MOV AH, 09 wWe cen check 
096A:0105 BAOE01 MOV —DX, 010E ovr frome 'S 
096A:0108 CD21 INT 21 ° ol 
096A:010A E2F7 LOOP 0103 ther e 
096A:010C CD20 INT 20 

096A:010E 48 DEC AX 

096A:010F 65 DB 65 

096A:0110 6C DB 6C 

096A:0111 6C DB 6C 

096A:0112 6F DB 6F 

096A:0113 2C20 SUB AL, 20 

096A:0115 776F JA 0186 

096A:0117 726C JB 0185 

096A:0119 64 DB 64 

096A:011A ODOA24 OR AX, 240A 

096A:011D 7403 JZ 0122 

096A:011F E976FF JMP 0098 

Hello, world 

Hello, worid 

Hello, world 

Hello, world 

Hello, world 


Program terminated normally 


A>hello = 
Hello, worl 

Hello, worid 
Hello, world 
Hello, worid 


Hello, world 


Use EDLIN to 
creat file 


exit EDLIN 


Assemble source 
file using masm 


Convert toa 

-€xe file using 

LINK 

We are creating a.com 
file so you can ignore 

this message 

Convert to .com 

Load debug and Program 


Display 
registers 


Unassemble so we can 
check our Program is 
there 

Execute 

lt worked! 

quit DEBUG 

Now try it from 


DOS command level 


END 


> ~ OO RR mete 
ae Oe ap. - 
. 
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Glossary of DOS Terminology 
ASCIZ: Any Null (Zero) Terminated ASCII string. 


COOKED and RAW: Character devices have two modes for I/O, ‘‘cooked” and 
‘raw’. Cooked mode is the default, and I/O in cooked mode is character at atime 
with Control C checking depending on whether BREAK is ON or OFF and 
depending on the function request (1 — 12 or XENIX reads and writes). RAW 
mode, on the other hand, really refers to absolutely RAW I/O. If you put a device 
in raw mode via the 44H function request defined in the programmer's reference 
manual, there will be no control C checking, echoing or editing of characters. 


For example, if the requesting program puts a device in RAW mode, and requests 
a write of 50,000 characters to the AUX device, the Device Driver will get a 
request from the DOS to write 50,000 characters from the buffer located at the 
DWORD transfer address. The driver will not return until the request is complete. 
Obviously, this 1/O will be fast. In cooked mode, DOS would perform a control C 
check at the console after each single character write. This is an overhead of 
50,000 control C checks. 


File Handle: In DOS 2.11, there is a system file table set up at boot time. By the 
time command.com gets control, all of the character devices have been entered 
into the system file table. The first 4 devices are in a specific order. The Oth entry 
(file handle 0) is Console Input which is open for READ ONLY. File handle 1 is 
Console Output — WRITE ONLY. Handle 2 is Standard Error output. Handle 3 is 
the AUX device, and Handle 4 is the PRN device. As new entries are made to the 
system file table, they are assigned the next numbers. When COMMAND.COM 
EXEC’s a program, the ‘‘CHILD” program “INHERITS” all of the handles that 
COMMAND.COM has open. IF you type on the command line: PROG < INFYLE 
> OUTFYLE this means that you want PROG to read its input from INFYLE 
instead of the CONsole and write its output to OUTFYLE instead of to console 
out. COMMAND.COM will close handle 0 and open INFYLE. It will DUP handle 
Handle 0. It will then close handle 1, standard out and open OUTFYLE which will 
now be assigned standard out. When PROG reads from standard in, or writes to 
standard out, it will be reading from and writing to INFYLE and OUTFYLE 
respectively. 


_ The 100H byte Program Segment Prefix contains a set of 20 1 byte entries which 
is an index into the system file table entries which it has open. If the first entry in 
the PSP has a value of 8, this means that the Program is using entry 8 in the 
system file table as standard input. This could be either a device or a file. Ifa child 
is EXEC'd, it inherits the files of its parent. The converse is not true. When a child 
program which opens AUX as standard IN and PRN as standard out returns, the 
Parent does not inherit the files of its child. 


ee EE tenement see ewe | mee 
~ - -- 
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The ENVIRONMENT 

DOS 2.11 introduces another feature of XENIX, the Environment. The 
environment is an upto 32K data area which consists of ASCIZ (null terminated) 
strings of the form: AAAA=BBBBBBB. The end of the environment is marked by 
two consecutive nulls. The word at 2CH in the program segment prefix points to 
the segment containing the start of the program’s environment. New variables 
can be added to the environment by use of the DOS SET command. Since Nulls 
have significance, the environment can not be used for storing Binary data. When 
a parent process (such as command.com) exec’s a child process, the child is 
given a COPY of the parent’s environment Parameters such as PROMPT= 
which specifies the style of prompt to be used by COMMAND are stored in the 
environment. 


The ARENA 

DOS employs a software memory management scheme. Blocks in memory are 
either OWNED by processes or are free. An owned block has an ID number which 
is the initial paragraph of the Program Segment Prefix of a process in memory 
(your program). Each block has a size as well. When your process is in memory, 
there is a 16 byte ARENA BLOCK immediately below it which identifies it and 
specifies how much memory is allocated. 


ALLOC’s and DEALLOC’s as described in the DOS programmer’s reference 
manual manipulate these blocks. The arena blocks form a linked list throughout 


memory. 


The EXE file has a 512 byte header which contains initial segment offsets and a 
table of relocation items. There are, in addition, two fields which specify how 
much memory the file requires. Currently, the ‘‘maxalloc”’ field is set to FFFF by 
the linker. COM files are pure binary and have no information stored anywhere to 
tell the DOS loader how much memory they will require. Both COM and EXE files, 
for different reasons will have all of memory allocated to them. Any ALLOC call 
which is not preceded by a MODIFY memory call (to free up some memory) will 
fail. Simply modify the amount of memory allocated to your process and then 
allocs and execs will succeed. 
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